@zseven-w/pen-core 0.6.0 → 0.7.0

package/src/__tests__/normalize-tree-layout.test.ts

@@ -0,0 +1,294 @@
+import { describe, it, expect } from 'vitest';
+import type { PenNode } from '@zseven-w/pen-types';
+import { normalizeTreeLayout } from '../layout/normalize-tree';
+
+const frame = (props: Partial<PenNode> & { children?: PenNode[] }): PenNode =>
+  ({
+    id: 'f1',
+    type: 'frame',
+    ...props,
+  }) as PenNode;
+
+const rect = (id: string, props: Partial<PenNode> = {}): PenNode =>
+  ({
+    id,
+    type: 'rectangle',
+    width: 50,
+    height: 30,
+    ...props,
+  }) as PenNode;
+
+describe('normalizeTreeLayout', () => {
+  it('leaves leaf rectangle nodes unchanged', () => {
+    const node = rect('a', { x: 10, y: 20 });
+    const before = JSON.stringify(node);
+    normalizeTreeLayout(node);
+    expect(JSON.stringify(node)).toBe(before);
+  });
+
+  it('preserves an explicit vertical layout', () => {
+    const node = frame({
+      layout: 'vertical',
+      children: [rect('a'), rect('b')],
+    });
+    normalizeTreeLayout(node);
+    expect((node as PenNode & { layout?: string }).layout).toBe('vertical');
+  });
+
+  it('does not overwrite horizontal layout set by a prior role resolver', () => {
+    // Simulates the navbar case: role resolver wrote layout='horizontal',
+    // children have no layout hints (inferLayout would return undefined),
+    // so normalize would otherwise fall back to 'vertical' and clobber the
+    // semantically correct value. It must not.
+    const node = frame({
+      layout: 'horizontal',
+      children: [rect('logo'), rect('links'), rect('cta')],
+    });
+    normalizeTreeLayout(node);
+    expect((node as PenNode & { layout?: string }).layout).toBe('horizontal');
+  });
+
+  it('preserves absolute positioning when all children carry x/y', () => {
+    // Frame with no layout and children that all carry explicit x/y is a
+    // deliberate absolute-positioning container (phone mockup internals,
+    // hero image with floating overlays, etc.). The fallback must not
+    // write `vertical` or strip the x/y.
+    const node = frame({
+      width: 300,
+      height: 600,
+      children: [
+        rect('statusBar', { x: 0, y: 0, width: 300, height: 44 }),
+        rect('content', { x: 16, y: 60, width: 268, height: 500 }),
+        rect('homeIndicator', { x: 100, y: 580, width: 100, height: 4 }),
+      ],
+    });
+    normalizeTreeLayout(node);
+    expect((node as PenNode & { layout?: string }).layout).toBeUndefined();
+    const kids = (node as PenNode & { children: PenNode[] }).children;
+    expect(kids[0].x).toBe(0);
+    expect(kids[0].y).toBe(0);
+    expect(kids[1].x).toBe(16);
+    expect(kids[1].y).toBe(60);
+    expect(kids[2].x).toBe(100);
+    expect(kids[2].y).toBe(580);
+  });
+
+  it('preserves absolute positioning when even one child carries x/y', () => {
+    // If the model tagged at least one child with explicit coordinates, we
+    // treat the container as absolute-positioned. This is conservative but
+    // avoids destroying hand-placed overlays.
+    const node = frame({
+      children: [rect('base'), rect('overlay', { x: 120, y: 80 })],
+    });
+    normalizeTreeLayout(node);
+    expect((node as PenNode & { layout?: string }).layout).toBeUndefined();
+    const kids = (node as PenNode & { children: PenNode[] }).children;
+    expect(kids[1].x).toBe(120);
+    expect(kids[1].y).toBe(80);
+  });
+
+  it('writes explicit horizontal layout when gap is the only hint', () => {
+    const node = frame({
+      gap: 12,
+      children: [rect('a'), rect('b')],
+    });
+    normalizeTreeLayout(node);
+    // inferLayout() currently treats gap as a horizontal signal — preserve that behavior.
+    expect((node as PenNode & { layout?: string }).layout).toBe('horizontal');
+  });
+
+  it('falls back to vertical for multi-child frames with no layout hints', () => {
+    const node = frame({
+      children: [rect('a'), rect('b'), rect('c')],
+    });
+    normalizeTreeLayout(node);
+    expect((node as PenNode & { layout?: string }).layout).toBe('vertical');
+  });
+
+  it('leaves single-child frame without a layout untouched', () => {
+    const node = frame({
+      children: [rect('a')],
+    });
+    normalizeTreeLayout(node);
+    expect((node as PenNode & { layout?: string }).layout).toBeUndefined();
+  });
+
+  it('strips x and y from children of an active layout frame', () => {
+    const node = frame({
+      layout: 'vertical',
+      children: [rect('a', { x: 99, y: 33 }), rect('b', { x: 12, y: 77 })],
+    });
+    normalizeTreeLayout(node);
+    const kids = (node as PenNode & { children: PenNode[] }).children;
+    expect('x' in kids[0]).toBe(false);
+    expect('y' in kids[0]).toBe(false);
+    expect('x' in kids[1]).toBe(false);
+    expect('y' in kids[1]).toBe(false);
+  });
+
+  it('keeps x and y on badge overlay children', () => {
+    const badge: PenNode = {
+      id: 'badge1',
+      type: 'rectangle',
+      role: 'badge',
+      width: 8,
+      height: 8,
+      x: 40,
+      y: 0,
+    } as PenNode;
+    const node = frame({
+      layout: 'horizontal',
+      children: [rect('a', { x: 5, y: 5 }), badge],
+    });
+    normalizeTreeLayout(node);
+    const kids = (node as PenNode & { children: PenNode[] }).children;
+    expect('x' in kids[0]).toBe(false);
+    expect('y' in kids[0]).toBe(false);
+    expect(kids[1].x).toBe(40);
+    expect(kids[1].y).toBe(0);
+  });
+
+  it('recurses into nested frames', () => {
+    // Neither inner nor outer children carry x/y, so both get the vertical
+    // fallback; the recursion visits the inner frame and writes its layout.
+    const inner = frame({
+      id: 'inner',
+      children: [rect('c'), rect('d')],
+    });
+    const outer = frame({
+      id: 'outer',
+      children: [inner, rect('b')],
+    });
+    normalizeTreeLayout(outer);
+    expect((outer as PenNode & { layout?: string }).layout).toBe('vertical');
+    expect((inner as PenNode & { layout?: string }).layout).toBe('vertical');
+  });
+
+  it('does not strip x/y when layout is "none"', () => {
+    const node = frame({
+      layout: 'none',
+      children: [rect('a', { x: 10, y: 20 }), rect('b', { x: 30, y: 40 })],
+    });
+    normalizeTreeLayout(node);
+    const kids = (node as PenNode & { children: PenNode[] }).children;
+    expect(kids[0].x).toBe(10);
+    expect(kids[0].y).toBe(20);
+    expect(kids[1].x).toBe(30);
+    expect(kids[1].y).toBe(40);
+  });
+
+  it('overlay-only children do not block the vertical fallback', () => {
+    // A container whose only positioned children are overlays (badges) is
+    // still considered "model forgot layout" — the overlays retain their
+    // coordinates while the base frame gets a vertical layout for the rest.
+    const badge: PenNode = {
+      id: 'badge1',
+      type: 'rectangle',
+      role: 'badge',
+      width: 8,
+      height: 8,
+      x: 40,
+      y: 0,
+    } as PenNode;
+    const node = frame({
+      children: [rect('a'), rect('b'), badge],
+    });
+    normalizeTreeLayout(node);
+    expect((node as PenNode & { layout?: string }).layout).toBe('vertical');
+    const kids = (node as PenNode & { children: PenNode[] }).children;
+    // badge still carries its absolute coordinates
+    expect(kids[2].x).toBe(40);
+    expect(kids[2].y).toBe(0);
+  });
+
+  it('does NOT verticalize when ALL non-overlay children are frames (overlay composition)', () => {
+    // This is the bug subagent diagnosed: AI emits a layout-less parent
+    // containing structured nested-frame children (e.g. ring + value-wrap,
+    // hero + floating-card overlay, badge stack). Children have no x/y
+    // because the AI assumed (0,0) would just work. The previous behavior
+    // would silently rewrite the parent to layout='vertical', stacking
+    // the frames into a list and breaking the intended overlay.
+    //
+    // New behavior: when every non-overlay child is a frame, treat it as
+    // an overlay container and leave layout undefined so the renderer
+    // respects the children's positions.
+    const inner1 = frame({ id: 'inner1', width: 80, height: 80 });
+    const inner2 = frame({ id: 'inner2', width: 80, height: 80 });
+    const outer = frame({
+      id: 'outer',
+      width: 80,
+      height: 80,
+      children: [inner1, inner2],
+    });
+    normalizeTreeLayout(outer);
+    expect((outer as PenNode & { layout?: string }).layout).toBeUndefined();
+  });
+
+  it('still verticalizes mixed text+shape stacks (frame + text) where vertical is the right call', () => {
+    // Counter-test for the widened composition-primitive rule. The rule
+    // must not over-trigger: a frame containing a nested frame plus a
+    // text node is a content stack and SHOULD be verticalized.
+    // Homogeneous shape-only children (frame+frame, frame+rect,
+    // ellipse+ellipse) signal composition; text or icon_font mixed in
+    // breaks the heuristic.
+    const inner = frame({ id: 'inner', children: [rect('c'), rect('d')] });
+    const outer = frame({
+      id: 'outer',
+      children: [inner, { id: 'label', type: 'text', content: 'Hello' } as unknown as PenNode],
+    });
+    normalizeTreeLayout(outer);
+    expect((outer as PenNode & { layout?: string }).layout).toBe('vertical');
+  });
+
+  it('does NOT verticalize all-ellipse concentric stacks (progress-ring pattern)', () => {
+    // The activity-rings regression: an LLM emits a layout-less parent
+    // with N concentric ellipses at (0,0), expecting them to render
+    // centered. The old all-FRAME-children heuristic missed this because
+    // the children were ellipses (not frames) and fell through to the
+    // vertical fallback, stacking the rings as a list. The widened
+    // composition-primitive rule now recognises ellipse-only children
+    // as a composition and leaves layout undefined.
+    const ellipse = (id: string, w: number, h: number): PenNode =>
+      ({ id, type: 'ellipse', width: w, height: h }) as PenNode;
+    const parent = frame({
+      id: 'rings',
+      width: 120,
+      height: 120,
+      children: [ellipse('outer', 120, 120), ellipse('middle', 84, 84), ellipse('inner', 52, 52)],
+    });
+    normalizeTreeLayout(parent);
+    expect((parent as PenNode & { layout?: string }).layout).toBeUndefined();
+  });
+
+  it('does NOT verticalize frame + ellipse (ring wrapped in a frame)', () => {
+    // A common composition: an outer frame background with a nested
+    // ellipse ring on top. Both are composition primitives, so the
+    // heuristic keeps layout undefined and lets the renderer use the
+    // children's own positioning.
+    const parent = frame({
+      id: 'avatar',
+      width: 80,
+      height: 80,
+      children: [
+        { id: 'bg', type: 'frame', width: 80, height: 80 } as unknown as PenNode,
+        { id: 'ring', type: 'ellipse', width: 80, height: 80 } as unknown as PenNode,
+      ],
+    });
+    normalizeTreeLayout(parent);
+    expect((parent as PenNode & { layout?: string }).layout).toBeUndefined();
+  });
+
+  it('STILL verticalizes rectangle-only stacks (list of cards, not an overlay)', () => {
+    // Rectangles are intentionally NOT in the composition-primitive set.
+    // 3 rectangles with no layout hints is almost always a content
+    // stack (card list, nav buttons, divider rows), so we keep the
+    // vertical fallback for it. Authors who really want a rectangle
+    // overlay composition must declare x/y on at least one child.
+    const parent = frame({
+      id: 'list',
+      children: [rect('a'), rect('b'), rect('c')],
+    });
+    normalizeTreeLayout(parent);
+    expect((parent as PenNode & { layout?: string }).layout).toBe('vertical');
+  });
+});

package/src/__tests__/normalize.test.ts

@@ -1,110 +1,149 @@
-import { describe, it, expect } from 'vitest'
-import type { PenDocument } from '@zseven-w/pen-types'
-import { normalizePenDocument } from '../normalize'
+import { describe, it, expect } from 'vitest';
+import type { PenDocument } from '@zseven-w/pen-types';
+import { normalizePenDocument } from '../normalize';
 
 describe('normalizePenDocument', () => {
   it('normalizes "color" fill type to "solid"', () => {
     const doc: PenDocument = {
       version: '1.0.0',
-      children: [{
-        id: '1', type: 'rectangle', x: 0, y: 0,
-        fill: [{ type: 'color' as 'solid', color: '#ff0000' }],
-      }],
-    }
-    const result = normalizePenDocument(doc)
-    const fill = (result.children[0] as { fill: Array<{ type: string }> }).fill
-    expect(fill[0].type).toBe('solid')
-  })
+      children: [
+        {
+          id: '1',
+          type: 'rectangle',
+          x: 0,
+          y: 0,
+          fill: [{ type: 'color' as 'solid', color: '#ff0000' }],
+        },
+      ],
+    };
+    const result = normalizePenDocument(doc);
+    const fill = (result.children[0] as { fill: Array<{ type: string }> }).fill;
+    expect(fill[0].type).toBe('solid');
+  });
 
   it('normalizes string fill shorthand to solid fill array', () => {
     const doc: PenDocument = {
       version: '1.0.0',
-      children: [{
-        id: '1', type: 'rectangle', x: 0, y: 0,
-        fill: '#ff0000' as unknown as Array<{ type: 'solid'; color: string }>,
-      }],
-    }
-    const result = normalizePenDocument(doc)
-    const fill = (result.children[0] as { fill: Array<{ type: string; color: string }> }).fill
-    expect(fill).toHaveLength(1)
-    expect(fill[0]).toEqual({ type: 'solid', color: '#ff0000' })
-  })
+      children: [
+        {
+          id: '1',
+          type: 'rectangle',
+          x: 0,
+          y: 0,
+          fill: '#ff0000' as unknown as Array<{ type: 'solid'; color: string }>,
+        },
+      ],
+    };
+    const result = normalizePenDocument(doc);
+    const fill = (result.children[0] as { fill: Array<{ type: string; color: string }> }).fill;
+    expect(fill).toHaveLength(1);
+    expect(fill[0]).toEqual({ type: 'solid', color: '#ff0000' });
+  });
 
   it('normalizes fill_container sizing', () => {
     const doc: PenDocument = {
       version: '1.0.0',
-      children: [{
-        id: '1', type: 'frame', x: 0, y: 0,
-        width: 'fill_container(300)' as unknown as number,
-        height: 'fill_container' as unknown as number,
-        children: [],
-      }],
-    }
-    const result = normalizePenDocument(doc)
-    const node = result.children[0] as { width: unknown; height: unknown }
-    expect(node.width).toBe('fill_container')
-    expect(node.height).toBe('fill_container')
-  })
+      children: [
+        {
+          id: '1',
+          type: 'frame',
+          x: 0,
+          y: 0,
+          width: 'fill_container(300)' as unknown as number,
+          height: 'fill_container' as unknown as number,
+          children: [],
+        },
+      ],
+    };
+    const result = normalizePenDocument(doc);
+    const node = result.children[0] as { width: unknown; height: unknown };
+    expect(node.width).toBe('fill_container');
+    expect(node.height).toBe('fill_container');
+  });
 
   it('normalizes fit_content with hint to number', () => {
     const doc: PenDocument = {
       version: '1.0.0',
-      children: [{
-        id: '1', type: 'frame', x: 0, y: 0,
-        width: 'fit_content(250)' as unknown as number,
-        height: 'fit_content' as unknown as number,
-        children: [],
-      }],
-    }
-    const result = normalizePenDocument(doc)
-    const node = result.children[0] as { width: unknown; height: unknown }
-    expect(node.width).toBe(250)
-    expect(node.height).toBe('fit_content')
-  })
+      children: [
+        {
+          id: '1',
+          type: 'frame',
+          x: 0,
+          y: 0,
+          width: 'fit_content(250)' as unknown as number,
+          height: 'fit_content' as unknown as number,
+          children: [],
+        },
+      ],
+    };
+    const result = normalizePenDocument(doc);
+    const node = result.children[0] as { width: unknown; height: unknown };
+    expect(node.width).toBe(250);
+    expect(node.height).toBe('fit_content');
+  });
 
   it('normalizes pages children too', () => {
     const doc: PenDocument = {
       version: '1.0.0',
-      pages: [{
-        id: 'p1', name: 'Page 1',
-        children: [{
-          id: '1', type: 'rectangle', x: 0, y: 0,
-          fill: [{ type: 'color' as 'solid', color: '#00ff00' }],
-        }],
-      }],
+      pages: [
+        {
+          id: 'p1',
+          name: 'Page 1',
+          children: [
+            {
+              id: '1',
+              type: 'rectangle',
+              x: 0,
+              y: 0,
+              fill: [{ type: 'color' as 'solid', color: '#00ff00' }],
+            },
+          ],
+        },
+      ],
       children: [],
-    }
-    const result = normalizePenDocument(doc)
-    const fill = (result.pages![0].children[0] as { fill: Array<{ type: string }> }).fill
-    expect(fill[0].type).toBe('solid')
-  })
+    };
+    const result = normalizePenDocument(doc);
+    const fill = (result.pages![0].children[0] as { fill: Array<{ type: string }> }).fill;
+    expect(fill[0].type).toBe('solid');
+  });
 
   it('normalizes string elements inside fill array', () => {
     const doc: PenDocument = {
       version: '1.0.0',
-      children: [{
-        id: '1', type: 'path', d: 'M0 0', x: 0, y: 0,
-        fill: ['#ff0000'] as unknown as Array<{ type: 'solid'; color: string }>,
-      }],
-    }
-    const result = normalizePenDocument(doc)
-    const fill = (result.children[0] as { fill: Array<{ type: string; color: string }> }).fill
-    expect(fill).toHaveLength(1)
-    expect(fill[0]).toEqual({ type: 'solid', color: '#ff0000' })
-  })
+      children: [
+        {
+          id: '1',
+          type: 'path',
+          d: 'M0 0',
+          x: 0,
+          y: 0,
+          fill: ['#ff0000'] as unknown as Array<{ type: 'solid'; color: string }>,
+        },
+      ],
+    };
+    const result = normalizePenDocument(doc);
+    const fill = (result.children[0] as { fill: Array<{ type: string; color: string }> }).fill;
+    expect(fill).toHaveLength(1);
+    expect(fill[0]).toEqual({ type: 'solid', color: '#ff0000' });
+  });
 
   it('preserves $variable references', () => {
     const doc: PenDocument = {
       version: '1.0.0',
-      children: [{
-        id: '1', type: 'rectangle', x: 0, y: 0,
-        fill: [{ type: 'solid', color: '$primary' }],
-        opacity: '$opacity' as unknown as number,
-      }],
-    }
-    const result = normalizePenDocument(doc)
-    const node = result.children[0] as { fill: Array<{ color: string }>; opacity: unknown }
-    expect(node.fill[0].color).toBe('$primary')
-    expect(node.opacity).toBe('$opacity')
-  })
-})
+      children: [
+        {
+          id: '1',
+          type: 'rectangle',
+          x: 0,
+          y: 0,
+          fill: [{ type: 'solid', color: '$primary' }],
+          opacity: '$opacity' as unknown as number,
+        },
+      ],
+    };
+    const result = normalizePenDocument(doc);
+    const node = result.children[0] as { fill: Array<{ color: string }>; opacity: unknown };
+    expect(node.fill[0].color).toBe('$primary');
+    expect(node.opacity).toBe('$opacity');
+  });
+});

package/src/__tests__/path-anchors.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  anchorsToPathData,
+  getPathBoundsFromAnchors,
+  inferPathAnchorPointType,
+  pathDataToAnchors,
+} from '../path-anchors';
+
+describe('path anchor utilities', () => {
+  it('parses cubic and line path commands into editable anchors', () => {
+    const result = pathDataToAnchors('M 10 20 C 30 40 50 60 70 80 L 90 100 Z');
+
+    expect(result).not.toBeNull();
+    expect(result?.closed).toBe(true);
+    expect(result?.anchors).toEqual([
+      {
+        x: 10,
+        y: 20,
+        handleIn: null,
+        handleOut: { x: 20, y: 20 },
+      },
+      {
+        x: 70,
+        y: 80,
+        handleIn: { x: -20, y: -20 },
+        handleOut: null,
+      },
+      {
+        x: 90,
+        y: 100,
+        handleIn: null,
+        handleOut: null,
+      },
+    ]);
+  });
+
+  it('rebuilds path data from editable anchors', () => {
+    const d = anchorsToPathData(
+      [
+        { x: 0, y: 0, handleIn: null, handleOut: { x: 10, y: 0 } },
+        { x: 30, y: 20, handleIn: { x: -5, y: -10 }, handleOut: null },
+        { x: 60, y: 20, handleIn: null, handleOut: null },
+      ],
+      false,
+    );
+
+    expect(d).toBe('M 0 0 C 10 0 25 10 30 20 L 60 20');
+  });
+
+  it('returns null for unsupported quadratic commands', () => {
+    expect(pathDataToAnchors('M 0 0 Q 10 10 20 0')).toBeNull();
+  });
+
+  it('measures cubic bounds from the actual bezier curve instead of the control box', () => {
+    const bounds = getPathBoundsFromAnchors(
+      [
+        { x: 0, y: 0, handleIn: null, handleOut: { x: 100, y: 100 } },
+        { x: 300, y: 0, handleIn: { x: -100, y: 100 }, handleOut: null },
+      ],
+      false,
+    );
+
+    expect(bounds.x).toBe(0);
+    expect(bounds.y).toBe(0);
+    expect(bounds.width).toBe(300);
+    expect(bounds.height).toBeCloseTo(75, 5);
+  });
+
+  it('infers path point types from handle geometry', () => {
+    expect(
+      inferPathAnchorPointType({
+        x: 0,
+        y: 0,
+        handleIn: null,
+        handleOut: null,
+      }),
+    ).toBe('corner');
+
+    expect(
+      inferPathAnchorPointType({
+        x: 0,
+        y: 0,
+        handleIn: { x: -20, y: 0 },
+        handleOut: { x: 20, y: 0 },
+      }),
+    ).toBe('mirrored');
+
+    expect(
+      inferPathAnchorPointType({
+        x: 0,
+        y: 0,
+        handleIn: { x: -20, y: 0 },
+        handleOut: { x: 10, y: 5 },
+      }),
+    ).toBe('independent');
+  });
+});