@zseven-w/pen-core 0.7.2 → 0.7.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zseven-w/pen-core",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Core document operations, tree utils, variables, layout engine for OpenPencil",
   "homepage": "https://github.com/ZSeven-W/openpencil/tree/main/packages/pen-core",
   "bugs": {
@@ -30,7 +30,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zseven-w/pen-types": "0.7.2",
+    "@zseven-w/pen-types": "0.7.4",
     "nanoid": "^5.1.6",
     "paper": "^0.12.18"
   },

package/src/__tests__/node-helpers.test.ts

@@ -1,30 +1,40 @@
 import { describe, it, expect } from 'vitest';
 import type { PenNode } from '@zseven-w/pen-types';
-import { isBadgeOverlayNode } from '../node-helpers';
+import { isOverlayNode } from '../node-helpers';
 
-describe('isBadgeOverlayNode', () => {
-  it('returns true for badge role', () => {
+describe('isOverlayNode', () => {
+  it('returns true for overlay role', () => {
+    const node: PenNode = { id: '1', type: 'rectangle', role: 'overlay' };
+    expect(isOverlayNode(node)).toBe(true);
+  });
+
+  it('returns false for badge role (inline component, not overlay)', () => {
     const node: PenNode = { id: '1', type: 'rectangle', role: 'badge' };
-    expect(isBadgeOverlayNode(node)).toBe(true);
+    expect(isOverlayNode(node)).toBe(false);
   });
 
-  it('returns true for pill role', () => {
+  it('returns false for pill role (inline component, not overlay)', () => {
     const node: PenNode = { id: '1', type: 'rectangle', role: 'pill' };
-    expect(isBadgeOverlayNode(node)).toBe(true);
+    expect(isOverlayNode(node)).toBe(false);
+  });
+
+  it('returns false for tag role (inline component, not overlay)', () => {
+    const node: PenNode = { id: '1', type: 'rectangle', role: 'tag' };
+    expect(isOverlayNode(node)).toBe(false);
   });
 
-  it('returns true for name containing "badge"', () => {
+  it('returns false for name containing "badge" without explicit role', () => {
     const node: PenNode = { id: '1', type: 'rectangle', name: 'Notification Badge' };
-    expect(isBadgeOverlayNode(node)).toBe(true);
+    expect(isOverlayNode(node)).toBe(false);
   });
 
-  it('returns true for name containing "overlay"', () => {
+  it('returns false for name containing "overlay" without explicit role', () => {
     const node: PenNode = { id: '1', type: 'rectangle', name: 'Image Overlay' };
-    expect(isBadgeOverlayNode(node)).toBe(true);
+    expect(isOverlayNode(node)).toBe(false);
   });
 
   it('returns false for regular nodes', () => {
     const node: PenNode = { id: '1', type: 'rectangle', name: 'Button' };
-    expect(isBadgeOverlayNode(node)).toBe(false);
+    expect(isOverlayNode(node)).toBe(false);
   });
 });

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

@@ -126,11 +126,11 @@ describe('normalizeTreeLayout', () => {
     expect('y' in kids[1]).toBe(false);
   });
 
-  it('keeps x and y on badge overlay children', () => {
-    const badge: PenNode = {
-      id: 'badge1',
+  it('keeps x and y on overlay children', () => {
+    const overlay: PenNode = {
+      id: 'overlay1',
       type: 'rectangle',
-      role: 'badge',
+      role: 'overlay',
       width: 8,
       height: 8,
       x: 40,
@@ -138,7 +138,7 @@ describe('normalizeTreeLayout', () => {
     } as PenNode;
     const node = frame({
       layout: 'horizontal',
-      children: [rect('a', { x: 5, y: 5 }), badge],
+      children: [rect('a', { x: 5, y: 5 }), overlay],
     });
     normalizeTreeLayout(node);
     const kids = (node as PenNode & { children: PenNode[] }).children;
@@ -178,25 +178,25 @@ describe('normalizeTreeLayout', () => {
   });
 
   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
+    // A container whose only positioned children are overlays 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',
+    const overlay: PenNode = {
+      id: 'overlay1',
       type: 'rectangle',
-      role: 'badge',
+      role: 'overlay',
       width: 8,
       height: 8,
       x: 40,
       y: 0,
     } as PenNode;
     const node = frame({
-      children: [rect('a'), rect('b'), badge],
+      children: [rect('a'), rect('b'), overlay],
     });
     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
+    // overlay still carries its absolute coordinates
     expect(kids[2].x).toBe(40);
     expect(kids[2].y).toBe(0);
   });

package/src/__tests__/strip-redundant-section-fills.test.ts

@@ -235,6 +235,58 @@ describe('stripRedundantSectionFills', () => {
     expect((deepInner as PenNode & { fill?: unknown }).fill).toEqual(solidFill('#0A0A0A'));
   });
 
+  it('strips stale #FFFFFF section fills on a dark root (legacy alternation residue)', () => {
+    // Regression guard for 2026-04-15: the legacy fixSectionAlternation
+    // painted #FFFFFF / #F8FAFC on unfilled section runs regardless of
+    // page theme. After the alternation skip for dark parents landed,
+    // stale docs (and weak-model hedges) still carry those whites.
+    // stripRedundantSectionFills must now clean them up.
+    const section1 = frame({
+      id: 's1',
+      name: 'Hero',
+      role: 'hero',
+      fill: solidFill('#FFFFFF'),
+    });
+    const section2 = frame({
+      id: 's2',
+      name: 'Stats',
+      role: 'stats-section',
+      fill: solidFill('#F8FAFC'),
+    });
+    const section3 = frame({
+      id: 's3',
+      name: 'CTA',
+      role: 'cta-section',
+      fill: solidFill('#FFFFFF'),
+    });
+    const root = frame({
+      id: 'root',
+      fill: solidFill('#111111'),
+      children: [section1, section2, section3],
+    });
+    const changed = stripRedundantSectionFills(root);
+    expect(changed).toBe(true);
+    expect((section1 as PenNode & { fill?: unknown }).fill).toBeUndefined();
+    expect((section2 as PenNode & { fill?: unknown }).fill).toBeUndefined();
+    expect((section3 as PenNode & { fill?: unknown }).fill).toBeUndefined();
+  });
+
+  it('strips a safe-light hedge even when the root has no fill', () => {
+    // Mirror of the existing "root frame without a fill" dark case: a
+    // bare #FFFFFF on a section root is almost certainly the sub-agent
+    // hedging against a missing background spec, not a deliberate choice.
+    const section = frame({
+      id: 'sec',
+      fill: solidFill('#FAFAFA'),
+    });
+    const root = frame({
+      id: 'root',
+      children: [section],
+    });
+    stripRedundantSectionFills(root);
+    expect((section as PenNode & { fill?: unknown }).fill).toBeUndefined();
+  });
+
   it('reproduces the M2.7 health-tracker case', () => {
     // Direct repro of the actual failure: root #1a1a2e, six section roots
     // all hardcoded #0A0A0A, including one real card. The six section

package/src/index.ts

@@ -143,7 +143,7 @@ export { type BooleanOpType, canBooleanOp, executeBooleanOp } from './boolean-op
 export { cssFontFamily } from './font-utils.js';
 
 // Node helpers
-export { isBadgeOverlayNode, sanitizeName } from './node-helpers.js';
+export { isOverlayNode, isBadgeOverlayNode, sanitizeName } from './node-helpers.js';
 
 // Design-MD parser
 export {

package/src/layout/engine.ts

@@ -1,6 +1,6 @@
 import type { PenNode, ContainerProps, SizingBehavior, Padding } from '@zseven-w/pen-types';
 export type { Padding } from '@zseven-w/pen-types';
-import { isBadgeOverlayNode } from '../node-helpers.js';
+import { isOverlayNode } from '../node-helpers.js';
 import {
   parseSizing,
   estimateTextWidth,
@@ -119,7 +119,7 @@ export function inferLayout(node: PenNode): 'horizontal' | undefined {
 export function fitContentWidth(node: PenNode, parentAvail?: number): number {
   if (!('children' in node) || !node.children?.length) return 0;
   const visibleChildren = node.children.filter(
-    (child) => isNodeVisible(child) && !isBadgeOverlayNode(child),
+    (child) => isNodeVisible(child) && !isOverlayNode(child),
   );
   if (visibleChildren.length === 0) return 0;
   const c = node as PenNode & ContainerProps;
@@ -147,7 +147,7 @@ export function fitContentWidth(node: PenNode, parentAvail?: number): number {
 export function fitContentHeight(node: PenNode, parentAvailW?: number): number {
   if (!('children' in node) || !node.children?.length) return 0;
   const visibleChildren = node.children.filter(
-    (child) => isNodeVisible(child) && !isBadgeOverlayNode(child),
+    (child) => isNodeVisible(child) && !isOverlayNode(child),
   );
   if (visibleChildren.length === 0) return 0;
   const c = node as PenNode & ContainerProps;
@@ -254,8 +254,8 @@ export function computeLayoutPositions(parent: PenNode, children: PenNode[]): Pe
   const layout = c.layout || inferLayout(parent);
   if (!layout || layout === 'none') return visibleChildren;
 
-  const badgeNodes = visibleChildren.filter(isBadgeOverlayNode);
-  const layoutChildren = visibleChildren.filter((ch) => !isBadgeOverlayNode(ch));
+  const overlayNodes = visibleChildren.filter(isOverlayNode);
+  const layoutChildren = visibleChildren.filter((ch) => !isOverlayNode(ch));
   if (layoutChildren.length === 0) return visibleChildren;
 
   const pW = parseSizing(c.width);
@@ -399,8 +399,8 @@ export function computeLayoutPositions(parent: PenNode, children: PenNode[]): Pe
     return out as unknown as PenNode;
   });
 
-  if (badgeNodes.length > 0) {
-    return [...badgeNodes, ...positioned];
+  if (overlayNodes.length > 0) {
+    return [...overlayNodes, ...positioned];
   }
   return positioned;
 }

package/src/layout/normalize-tree.ts

@@ -1,5 +1,5 @@
 import type { PenNode, ContainerProps } from '@zseven-w/pen-types';
-import { isBadgeOverlayNode } from '../node-helpers.js';
+import { isOverlayNode } from '../node-helpers.js';
 import { inferLayout } from './engine.js';
 
 /**
@@ -17,8 +17,8 @@ import { inferLayout } from './engine.js';
  *      images with floating overlays, etc.) and we leave it alone.
  *
  * 2. When a frame has an active layout (`vertical` or `horizontal`), strip
- *    `x`/`y` from every non-overlay child. Overlay children (badges, pills,
- *    tags, floating indicators) keep their absolute coordinates.
+ *    `x`/`y` from every non-overlay child. Overlay children (opt-in via
+ *    `role: 'overlay'`) keep their absolute coordinates.
  *
  * Used as a post-generation pass after an AI model produces a subtree. It
  * corrects two common model mistakes:
@@ -58,7 +58,7 @@ export function normalizeTreeLayout(node: PenNode): void {
     // (2) Strip x/y from non-overlay children of active-layout frames.
     if (c.layout === 'vertical' || c.layout === 'horizontal') {
       for (const child of children) {
-        if (!isBadgeOverlayNode(child)) {
+        if (!isOverlayNode(child)) {
           if ('x' in child) delete (child as { x?: number }).x;
           if ('y' in child) delete (child as { y?: number }).y;
         }
@@ -105,9 +105,9 @@ export function normalizeTreeLayout(node: PenNode): void {
  *      still get the vertical fallback, because those are typically
  *      content stacks where verticalization is the right call.
  *
- * Overlay nodes (badges/pills/tags via `isBadgeOverlayNode`) are excluded
- * from the count — they legitimately carry x/y inside auto-layout frames
- * and shouldn't tip the heuristic.
+ * Overlay nodes (opt-in via `role: 'overlay'`, detected by `isOverlayNode`)
+ * are excluded from the count — they legitimately carry x/y inside
+ * auto-layout frames and shouldn't tip the heuristic.
  *
  * This is intentionally conservative: it accepts a few false negatives
  * (some genuinely vertical all-shape stacks will be left un-normalized,
@@ -120,7 +120,7 @@ const COMPOSITION_PRIMITIVE_TYPES = new Set(['frame', 'ellipse', 'path']);
 function hasAbsolutePositionedChild(children: PenNode[]): boolean {
   // Signal 1: explicit numeric x/y on any non-overlay child.
   for (const child of children) {
-    if (isBadgeOverlayNode(child)) continue;
+    if (isOverlayNode(child)) continue;
     const c = child as PenNode & { x?: number; y?: number };
     if (typeof c.x === 'number' || typeof c.y === 'number') return true;
   }
@@ -130,7 +130,7 @@ function hasAbsolutePositionedChild(children: PenNode[]): boolean {
   let nonOverlayCount = 0;
   let primitiveCount = 0;
   for (const child of children) {
-    if (isBadgeOverlayNode(child)) continue;
+    if (isOverlayNode(child)) continue;
     nonOverlayCount++;
     if (COMPOSITION_PRIMITIVE_TYPES.has(child.type)) primitiveCount++;
   }

package/src/layout/strip-redundant-section-fills.ts

@@ -126,13 +126,41 @@ const SAFE_DARK_HEXES = new Set([
   '#202020',
 ]);
 
+/**
+ * Light-mode counterparts of SAFE_DARK_HEXES. Two sources produce these
+ * on section roots:
+ *   1. Weaker sub-agents that hedge with pure white / near-white instead
+ *      of the role-correct transparent fill.
+ *   2. The legacy `fixSectionAlternation` post-pass that painted an
+ *      #FFFFFF / #F8FAFC ladder on every run of ≥3 unfilled sections.
+ *      On dark pages that ladder leaves visible white strips; if a doc
+ *      with those stale fills is re-opened or re-rendered after the
+ *      alternation skip landed, the fills are still there and the skip
+ *      alone won't remove them.
+ * Treat these the same as safe-dark hedges: strip on any section root.
+ */
+const SAFE_LIGHT_HEXES = new Set([
+  '#ffffff',
+  '#fff',
+  '#fefefe',
+  '#fdfdfd',
+  '#fcfcfc',
+  '#fafafa',
+  '#f9fafb',
+  '#f8f8f8',
+  '#f8fafc',
+  '#f5f5f5',
+  '#f4f4f5',
+  '#f3f4f6',
+]);
+
 function shouldStripFill(childFill: string, rootFill: string | null): boolean {
   const childKey = normalizeHex(childFill);
   if (rootFill) {
     const rootKey = normalizeHex(rootFill);
     if (childKey === rootKey) return true;
   }
-  return SAFE_DARK_HEXES.has(childKey);
+  return SAFE_DARK_HEXES.has(childKey) || SAFE_LIGHT_HEXES.has(childKey);
 }
 
 function normalizeHex(color: string): string {

package/src/node-helpers.ts

@@ -1,18 +1,34 @@
 import type { PenNode } from '@zseven-w/pen-types';
 
 /**
- * Check if a node is a badge/overlay that uses absolute positioning
- * and should not participate in layout flow.
+ * Check if a node is an overlay that uses absolute positioning and should
+ * not participate in layout flow.
+ *
+ * Requires explicit `role: 'overlay'`. Earlier versions matched on
+ * `role: 'badge' | 'pill' | 'tag'` plus name regexes, but those are
+ * inline-component markers in this repo (see `role-resolver.ts` and
+ * `strip-redundant-section-fills.ts` PROTECTED_ROLES) — pulling them out
+ * of layout flow collapsed them to (0,0) of their parent and stacked
+ * them on top of siblings. `role: 'overlay'` is the dedicated opt-in for
+ * notification dots and true floating decorations.
  */
-export function isBadgeOverlayNode(node: PenNode): boolean {
+export function isOverlayNode(node: PenNode): boolean {
   if ('role' in node) {
     const role = (node as { role?: string }).role;
-    if (role === 'badge' || role === 'pill' || role === 'tag') return true;
+    if (role === 'overlay') return true;
   }
-  const name = (node.name ?? '').toLowerCase();
-  return /badge|indicator|notification[-_\s]?dot|overlay|floating/i.test(name);
+  return false;
 }
 
+/**
+ * @deprecated Renamed to `isOverlayNode`. Semantics also tightened:
+ * this alias no longer returns true for `role: 'badge' | 'pill' | 'tag'`
+ * (those are inline-component roles in this repo and should flow in
+ * auto-layout, not float). Use `isOverlayNode` and mark true floating
+ * decorations with `role: 'overlay'`.
+ */
+export const isBadgeOverlayNode = isOverlayNode;
+
 /**
  * Convert a name string to PascalCase.
  * Strips non-alphanumeric characters and joins words.