@zseven-w/pen-core 0.5.2 → 0.7.0

package/src/normalize/normalize-stroke-fill-schema.ts

@@ -0,0 +1,297 @@
+import type { PenNode, PenFill, PenStroke, SolidFill } from '@zseven-w/pen-types';
+
+/**
+ * Normalize stroke/fill schema violations commonly emitted by AI sub-agents
+ * (MiniMax M2.7, GLM, Kimi) that don't strictly follow the PenNode types.
+ *
+ * Three classes of schema violation are repaired in place, recursively
+ * across the tree:
+ *
+ * 1. `stroke` as an array of one entry — AI wraps the stroke object in an
+ *    array as if it were `fill` (which IS an array). We unwrap the first
+ *    element and continue normalizing it.
+ *
+ * 2. Stroke value shaped like a `SolidFill` ({ type, color }) instead of
+ *    a `PenStroke` ({ thickness, fill }). We migrate the inner `color`
+ *    into a proper `stroke.fill[0]`, pull the `strokeWidth` top-level
+ *    field (the CSS/SVG-style spelling that many models emit) into
+ *    `stroke.thickness`, and delete the stray `strokeWidth`. If neither
+ *    a thickness nor a strokeWidth is present, default to 2 so the
+ *    stroke actually draws something.
+ *
+ * 3. Fill entries with illegal CSS-keyword colors (`"none"`, `"transparent"`)
+ *    are dropped. The 8-digit transparent hex (`"#00000000"`) is valid
+ *    and kept. The same rule applies to any `stroke.fill[]` entries.
+ *
+ * Returns nothing — the tree is mutated in place, matching the other
+ * pen-core normalize passes. Callers that rely on Zustand publish
+ * semantics should route the result through `forcePageResync()` the same
+ * way they already do for other mutating post-streaming passes.
+ */
+export function normalizeStrokeFillSchema(node: PenNode): void {
+  normalizeNodeStroke(node);
+  normalizeNodeFill(node);
+
+  if ('children' in node && Array.isArray(node.children)) {
+    for (const child of node.children) {
+      normalizeStrokeFillSchema(child);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Stroke normalization
+// ---------------------------------------------------------------------------
+
+interface MaybeStrokeHolder {
+  stroke?: unknown;
+  strokeWidth?: unknown;
+  'stroke-width'?: unknown;
+  'stroke-dasharray'?: unknown;
+  'stroke-dashoffset'?: unknown;
+  'stroke-linecap'?: unknown;
+  'stroke-linejoin'?: unknown;
+}
+
+function normalizeNodeStroke(node: PenNode): void {
+  const rec = node as unknown as MaybeStrokeHolder;
+  const rawStroke = rec.stroke;
+  const hasSvgStrokeAttrs =
+    rec['stroke-width'] !== undefined ||
+    rec['stroke-dasharray'] !== undefined ||
+    rec['stroke-dashoffset'] !== undefined ||
+    rec['stroke-linecap'] !== undefined ||
+    rec['stroke-linejoin'] !== undefined;
+  if ((rawStroke === undefined || rawStroke === null) && !hasSvgStrokeAttrs) return;
+
+  // (1) Unwrap `stroke: [ ... ]` by taking the first element.
+  let stroke: unknown = rawStroke;
+  if (typeof stroke === 'string') {
+    stroke = { type: 'solid', color: stroke };
+  }
+  if (Array.isArray(stroke)) {
+    stroke = stroke.length > 0 ? stroke[0] : undefined;
+  }
+  if ((!stroke || typeof stroke !== 'object') && !hasSvgStrokeAttrs) {
+    delete rec.stroke;
+    delete rec.strokeWidth;
+    delete rec['stroke-width'];
+    delete rec['stroke-dasharray'];
+    delete rec['stroke-dashoffset'];
+    delete rec['stroke-linecap'];
+    delete rec['stroke-linejoin'];
+    return;
+  }
+
+  // (2) Detect the fill-shape-as-stroke pattern and migrate it.
+  const maybeFillShape = (stroke ?? {}) as {
+    type?: unknown;
+    color?: unknown;
+    thickness?: unknown;
+    fill?: unknown;
+  };
+  const looksLikeFillShape =
+    typeof maybeFillShape.type === 'string' &&
+    typeof maybeFillShape.color === 'string' &&
+    maybeFillShape.thickness === undefined &&
+    maybeFillShape.fill === undefined;
+
+  if (looksLikeFillShape) {
+    const thickness = readThickness(rec);
+    rec.stroke = {
+      thickness,
+      fill: [
+        {
+          type: 'solid',
+          color: maybeFillShape.color as string,
+        } as SolidFill,
+      ],
+    } as PenStroke;
+    delete rec.strokeWidth;
+    // Now clean illegal color inside the migrated stroke.fill
+    stripIllegalColorsFromStrokeFill(node);
+    return;
+  }
+
+  // Otherwise we have something that looks like a real PenStroke — fix
+  // missing thickness, clean up illegal colors, and persist any
+  // strokeWidth field that survived as a top-level property.
+  const strokeObj = (stroke ?? {}) as Partial<PenStroke> & { [k: string]: unknown };
+  if (strokeObj.thickness === undefined || strokeObj.thickness === null) {
+    const width = readThickness(rec);
+    (strokeObj as { thickness?: number }).thickness = width;
+  }
+  const dashPattern = readDashPattern(rec['stroke-dasharray']);
+  if (dashPattern && dashPattern.length > 0 && strokeObj.dashPattern === undefined) {
+    strokeObj.dashPattern = dashPattern;
+  }
+  const dashOffset = readDashOffset(rec['stroke-dashoffset']);
+  if (dashOffset !== null && strokeObj.dashOffset === undefined) {
+    strokeObj.dashOffset = dashOffset;
+  }
+  const cap = readCap(rec['stroke-linecap']);
+  if (cap && strokeObj.cap === undefined) {
+    strokeObj.cap = cap;
+  }
+  const join = readJoin(rec['stroke-linejoin']);
+  if (join && strokeObj.join === undefined) {
+    strokeObj.join = join;
+  }
+  if (
+    (!Array.isArray(strokeObj.fill) || strokeObj.fill.length === 0) &&
+    typeof maybeFillShape.color !== 'string'
+  ) {
+    const inferredColor = inferStrokeColor(node);
+    if (inferredColor) {
+      strokeObj.fill = [{ type: 'solid', color: inferredColor }] as PenFill[];
+    }
+  }
+  rec.stroke = strokeObj as PenStroke;
+  delete rec.strokeWidth;
+  delete rec['stroke-width'];
+  delete rec['stroke-dasharray'];
+  delete rec['stroke-dashoffset'];
+  delete rec['stroke-linecap'];
+  delete rec['stroke-linejoin'];
+  stripIllegalColorsFromStrokeFill(node);
+
+  // If after cleanup the stroke has no fill at all, drop the whole stroke.
+  const cleaned = rec.stroke as PenStroke | undefined;
+  if (cleaned && (!cleaned.fill || cleaned.fill.length === 0)) {
+    delete rec.stroke;
+  }
+}
+
+function readThickness(rec: MaybeStrokeHolder): number {
+  const raw = rec.strokeWidth ?? rec['stroke-width'];
+  if (typeof raw === 'number' && raw > 0) return raw;
+  if (typeof raw === 'string') {
+    const n = parseFloat(raw);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return 2;
+}
+
+function readDashPattern(raw: unknown): number[] | null {
+  if (Array.isArray(raw)) {
+    const nums = raw.filter((value): value is number => typeof value === 'number' && value > 0);
+    if (nums.length === 1) return [nums[0], nums[0]];
+    return nums.length > 0 ? nums : null;
+  }
+  if (typeof raw === 'string') {
+    const nums = raw
+      .split(/[,\s]+/)
+      .map((part) => parseFloat(part))
+      .filter((value) => Number.isFinite(value) && value > 0);
+    if (nums.length === 1) return [nums[0], nums[0]];
+    return nums.length > 0 ? nums : null;
+  }
+  return null;
+}
+
+function readDashOffset(raw: unknown): number | null {
+  if (typeof raw === 'number' && Number.isFinite(raw)) return raw;
+  if (typeof raw === 'string') {
+    const parsed = parseFloat(raw);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return null;
+}
+
+function readCap(raw: unknown): PenStroke['cap'] | null {
+  return raw === 'round' || raw === 'square' || raw === 'none' ? raw : null;
+}
+
+function readJoin(raw: unknown): PenStroke['join'] | null {
+  return raw === 'round' || raw === 'bevel' || raw === 'miter' ? raw : null;
+}
+
+function inferStrokeColor(node: PenNode): string | null {
+  const name = typeof node.name === 'string' ? node.name.toLowerCase() : '';
+  if (/track/.test(name)) return '#2A2A2A';
+  if (/(progress|chart line|line|curve|wave)/.test(name)) return '#22C55E';
+  return null;
+}
+
+function stripIllegalColorsFromStrokeFill(node: PenNode): void {
+  const rec = node as unknown as { stroke?: { fill?: unknown } };
+  const stroke = rec.stroke;
+  if (!stroke || typeof stroke !== 'object') return;
+  const fillArr = stroke.fill;
+  if (!Array.isArray(fillArr)) return;
+  (stroke as { fill?: PenFill[] }).fill = fillArr.filter((f) => isLegalFillEntry(f)) as PenFill[];
+}
+
+// ---------------------------------------------------------------------------
+// Fill normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * Explicit transparent hex. Used for SHAPE fills (frame, rectangle,
+ * ellipse, path, group…) where "no fill" really means a hollow shape
+ * that should let the background show through. We write the 8-digit
+ * transparent hex so canvas-object-factory doesn't fall back to an
+ * opaque default gray fill.
+ */
+const EXPLICIT_TRANSPARENT_FILL: SolidFill = {
+  type: 'solid',
+  color: '#00000000',
+};
+
+/**
+ * Node types whose `fill` represents a FOREGROUND color (text color,
+ * icon color) rather than a shape's background. On these types an
+ * illegal "none" / "transparent" fill is almost certainly a mistake:
+ * the user meant "default text color", not "invisible text". Freezing
+ * them to #00000000 would hide the content entirely, so we delete the
+ * field and let downstream layers (role defaults, button contrast,
+ * style inheritance) supply a visible color.
+ */
+const FOREGROUND_NODE_TYPES = new Set<string>(['text', 'icon_font']);
+
+function normalizeNodeFill(node: PenNode): void {
+  const rec = node as unknown as { fill?: unknown };
+  const raw = rec.fill;
+  if (!raw) return;
+  if (!Array.isArray(raw)) return;
+  // Separate legal entries from CSS-keyword illegal entries.
+  const cleaned = raw.filter((f) => isLegalFillEntry(f));
+  if (cleaned.length > 0) {
+    rec.fill = cleaned as PenFill[];
+    return;
+  }
+  // Empty in, empty out — leave unchanged.
+  if (raw.length === 0) {
+    rec.fill = [] as PenFill[];
+    return;
+  }
+  // Every original entry was a CSS keyword ("none" / "transparent").
+  // The correct repair depends on whether `fill` is a background or a
+  // foreground color on this node type:
+  //
+  //   SHAPE types (frame, rectangle, ellipse, path, group, …)
+  //     fill = shape background. "no fill" means hollow. Keep the
+  //     explicit transparent hex so canvas doesn't fall back to the
+  //     default gray fill.
+  //
+  //   FOREGROUND types (text, icon_font)
+  //     fill = text/icon color. "no fill" would hide the content —
+  //     almost certainly not what the AI meant. Delete the field so
+  //     downstream layers can populate a visible color.
+  if (FOREGROUND_NODE_TYPES.has(node.type)) {
+    delete rec.fill;
+  } else {
+    rec.fill = [EXPLICIT_TRANSPARENT_FILL] as PenFill[];
+  }
+}
+
+/** Reject fill entries whose color is an unsupported CSS keyword. */
+function isLegalFillEntry(entry: unknown): boolean {
+  if (!entry || typeof entry !== 'object') return false;
+  const e = entry as { type?: unknown; color?: unknown };
+  if (e.type === 'solid' && typeof e.color === 'string') {
+    const c = e.color.trim().toLowerCase();
+    if (c === 'none' || c === 'transparent') return false;
+  }
+  return true;
+}

package/src/normalize.ts

@@ -13,8 +13,8 @@
  * canvas render time, preserving $variable bindings in the document.
  */
 
-import type { PenDocument, PenNode } from '@zseven-w/pen-types'
-import type { PenFill, PenStroke, GradientStop } from '@zseven-w/pen-types'
+import type { PenDocument, PenNode } from '@zseven-w/pen-types';
+import type { PenFill, PenStroke, GradientStop } from '@zseven-w/pen-types';
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -24,15 +24,15 @@ export function normalizePenDocument(doc: PenDocument): PenDocument {
   const normalized = {
     ...doc,
     children: doc.children.map((n) => normalizeNode(n)),
-  }
+  };
   // Normalize all pages' children too
   if (normalized.pages && normalized.pages.length > 0) {
     normalized.pages = normalized.pages.map((p) => ({
       ...p,
       children: p.children.map((n) => normalizeNode(n)),
-    }))
+    }));
   }
-  return normalized
+  return normalized;
 }
 
 // ---------------------------------------------------------------------------
@@ -40,42 +40,48 @@ export function normalizePenDocument(doc: PenDocument): PenDocument {
 // ---------------------------------------------------------------------------
 
 function normalizeNode(node: PenNode): PenNode {
-  const out: Record<string, unknown> = { ...node }
+  const out: Record<string, unknown> = { ...node };
 
   // fill
   if ('fill' in out && out.fill !== undefined) {
-    out.fill = normalizeFills(out.fill)
+    out.fill = normalizeFills(out.fill);
   }
 
   // stroke
   if ('stroke' in out && out.stroke != null) {
-    out.stroke = normalizeStroke(out.stroke as Record<string, unknown>)
+    out.stroke = normalizeStroke(out.stroke as Record<string, unknown>);
   }
 
   // effects — pass through (no format changes needed)
 
   // sizing
-  if ('width' in out) out.width = normalizeSizing(out.width)
-  if ('height' in out) out.height = normalizeSizing(out.height)
+  if ('width' in out) out.width = normalizeSizing(out.width);
+  if ('height' in out) out.height = normalizeSizing(out.height);
 
   // gap — pass through ($variable strings preserved)
 
   // padding — normalize array format only (not variable resolution)
-  if ('padding' in out) out.padding = normalizePadding(out.padding)
+  if ('padding' in out) out.padding = normalizePadding(out.padding);
 
   // opacity — pass through ($variable strings preserved)
 
+  // text nodes: normalize `text` field to `content` (MCP/CLI use `text`, renderer expects `content`)
+  if (out.type === 'text' && !('content' in out) && typeof out.text === 'string') {
+    out.content = out.text as string;
+    delete out.text;
+  }
+
   // icon_font: default to lucide family
   if (out.type === 'icon_font' && !out.iconFontFamily) {
-    out.iconFontFamily = 'lucide'
+    out.iconFontFamily = 'lucide';
   }
 
   // children
   if ('children' in out && Array.isArray(out.children)) {
-    out.children = (out.children as PenNode[]).map((c) => normalizeNode(c))
+    out.children = (out.children as PenNode[]).map((c) => normalizeNode(c));
   }
 
-  return out as unknown as PenNode
+  return out as unknown as PenNode;
 }
 
 // ---------------------------------------------------------------------------
@@ -83,66 +89,64 @@ function normalizeNode(node: PenNode): PenNode {
 // ---------------------------------------------------------------------------
 
 function normalizeFills(raw: unknown): PenFill[] {
-  if (!raw) return []
+  if (!raw) return [];
 
   // String shorthand: "#hex" or "$variable" → solid fill
   if (typeof raw === 'string') {
-    return [{ type: 'solid', color: raw }]
+    return [{ type: 'solid', color: raw }];
   }
 
   // Array of fills
   if (Array.isArray(raw)) {
-    return raw.map((f) => normalizeSingleFill(f)).filter(Boolean) as PenFill[]
+    return raw.map((f) => normalizeSingleFill(f)).filter(Boolean) as PenFill[];
   }
 
   // Single fill object
   if (typeof raw === 'object') {
-    const f = normalizeSingleFill(raw as Record<string, unknown>)
-    return f ? [f] : []
+    const f = normalizeSingleFill(raw as Record<string, unknown>);
+    return f ? [f] : [];
   }
 
-  return []
+  return [];
 }
 
-function normalizeSingleFill(
-  raw: Record<string, unknown> | string,
-): PenFill | null {
+function normalizeSingleFill(raw: Record<string, unknown> | string): PenFill | null {
   // String shorthand inside array: "#hex" or "$variable" → solid fill
   if (typeof raw === 'string') {
-    return raw ? { type: 'solid', color: raw } : null
+    return raw ? { type: 'solid', color: raw } : null;
   }
-  if (!raw || typeof raw !== 'object') return null
-  const t = raw.type as string | undefined
+  if (!raw || typeof raw !== 'object') return null;
+  const t = raw.type as string | undefined;
 
   // Pencil "color" → OpenPencil "solid"
   if (t === 'color' || t === 'solid') {
     return {
       type: 'solid',
       color: typeof raw.color === 'string' ? raw.color : '#000000',
-    }
+    };
   }
 
   // Pencil "gradient" → split by gradientType
   if (t === 'gradient') {
-    const gt = (raw.gradientType as string) ?? 'linear'
-    const stops = normalizeGradientStops(raw.colors as unknown[])
+    const gt = (raw.gradientType as string) ?? 'linear';
+    const stops = normalizeGradientStops(raw.colors as unknown[]);
 
     if (gt === 'radial') {
-      const center = raw.center as Record<string, unknown> | undefined
+      const center = raw.center as Record<string, unknown> | undefined;
       return {
         type: 'radial_gradient',
         cx: typeof center?.x === 'number' ? center.x : 0.5,
         cy: typeof center?.y === 'number' ? center.y : 0.5,
         radius: 0.5,
         stops,
-      }
+      };
     }
     // linear or angular
     return {
       type: 'linear_gradient',
       angle: typeof raw.rotation === 'number' ? raw.rotation : 0,
       stops,
-    }
+    };
   }
 
   // Already our format
@@ -152,85 +156,81 @@ function normalizeSingleFill(
         ? normalizeGradientStops(raw.stops as unknown[])
         : 'colors' in raw
           ? normalizeGradientStops(raw.colors as unknown[])
-          : []
-    return { ...(raw as unknown as PenFill), stops } as PenFill
+          : [];
+    return { ...(raw as unknown as PenFill), stops } as PenFill;
   }
 
   // Image fill — pass through
-  if (t === 'image') return raw as unknown as PenFill
+  if (t === 'image') return raw as unknown as PenFill;
 
   // Fallback: if there's a color field, treat as solid
   if ('color' in raw) {
     return {
       type: 'solid',
       color: typeof raw.color === 'string' ? raw.color : '#000000',
-    }
+    };
   }
 
-  return null
+  return null;
 }
 
-function normalizeGradientStops(
-  raw: unknown[] | undefined,
-): GradientStop[] {
-  if (!Array.isArray(raw) || raw.length === 0) return []
+function normalizeGradientStops(raw: unknown[] | undefined): GradientStop[] {
+  if (!Array.isArray(raw) || raw.length === 0) return [];
 
   // First pass: parse offsets, collecting which ones are explicitly set
   const parsed = raw.map((s: unknown) => {
-    const stop = s as Record<string, unknown>
+    const stop = s as Record<string, unknown>;
     const rawOffset =
       typeof stop.offset === 'number' && Number.isFinite(stop.offset)
         ? stop.offset
         : typeof stop.position === 'number' && Number.isFinite(stop.position)
           ? stop.position
-          : null
+          : null;
     // Normalize percentage-format offsets (AI sometimes outputs 0-100 instead of 0-1)
-    const offset = rawOffset !== null && rawOffset > 1 ? rawOffset / 100 : rawOffset
+    const offset = rawOffset !== null && rawOffset > 1 ? rawOffset / 100 : rawOffset;
     return {
       offset,
       color: typeof stop.color === 'string' ? stop.color : '#000000',
-    }
-  })
+    };
+  });
 
   // Second pass: auto-distribute any stops that are missing an offset
-  const n = parsed.length
+  const n = parsed.length;
   return parsed.map((s, i) => ({
     color: s.color,
     offset: s.offset !== null ? Math.max(0, Math.min(1, s.offset!)) : i / Math.max(n - 1, 1),
-  }))
+  }));
 }
 
 // ---------------------------------------------------------------------------
 // Stroke normalization
 // ---------------------------------------------------------------------------
 
-function normalizeStroke(
-  raw: Record<string, unknown>,
-): PenStroke | undefined {
-  if (!raw) return undefined
-  const out = { ...raw }
+function normalizeStroke(raw: Record<string, unknown>): PenStroke | undefined {
+  if (!raw) return undefined;
+  const out = { ...raw };
 
   // Normalize fill inside stroke
   if ('fill' in out) {
-    out.fill = normalizeFills(out.fill)
+    out.fill = normalizeFills(out.fill);
   }
 
   // Pencil may use "color" directly on stroke
   if ('color' in out && typeof out.color === 'string') {
-    out.fill = [{ type: 'solid', color: out.color as string }]
-    delete out.color
+    out.fill = [{ type: 'solid', color: out.color as string }];
+    delete out.color;
   }
 
   // Thickness: leave $variable strings as-is, normalise plain number strings
   if (typeof out.thickness === 'string') {
-    const str = out.thickness as string
+    const str = out.thickness as string;
     if (!str.startsWith('$')) {
-      const num = parseFloat(str)
-      out.thickness = isNaN(num) ? 1 : num
+      const num = parseFloat(str);
+      out.thickness = isNaN(num) ? 1 : num;
     }
   }
 
-  return out as unknown as PenStroke
+  return out as unknown as PenStroke;
 }
 
 // ---------------------------------------------------------------------------
@@ -238,46 +238,46 @@ function normalizeStroke(
 // ---------------------------------------------------------------------------
 
 function normalizeSizing(value: unknown): number | string {
-  if (typeof value === 'number') return value
-  if (typeof value !== 'string') return 0
+  if (typeof value === 'number') return value;
+  if (typeof value !== 'string') return 0;
 
   // $variable — pass through
-  if (value.startsWith('$')) return value
+  if (value.startsWith('$')) return value;
 
   // fill_container must always resolve dynamically from parent dimensions
-  if (value.startsWith('fill_container')) return 'fill_container'
+  if (value.startsWith('fill_container')) return 'fill_container';
 
   // fit_content with a hint value: use the hint (more accurate than our estimation)
   if (value.startsWith('fit_content')) {
-    const match = value.match(/\((\d+(?:\.\d+)?)\)/)
-    if (match) return parseFloat(match[1])
-    return 'fit_content'
+    const match = value.match(/\((\d+(?:\.\d+)?)\)/);
+    if (match) return parseFloat(match[1]);
+    return 'fit_content';
   }
 
   // Try as a plain number string
-  const num = parseFloat(value)
-  return isNaN(num) ? 0 : num
+  const num = parseFloat(value);
+  return isNaN(num) ? 0 : num;
 }
 
 function normalizePadding(
   value: unknown,
 ): number | [number, number] | [number, number, number, number] | string | undefined {
-  if (typeof value === 'number') return value
+  if (typeof value === 'number') return value;
   if (typeof value === 'string') {
     // $variable — pass through
-    if (value.startsWith('$')) return value
-    const num = parseFloat(value)
-    return isNaN(num) ? 0 : num
+    if (value.startsWith('$')) return value;
+    const num = parseFloat(value);
+    return isNaN(num) ? 0 : num;
   }
   if (Array.isArray(value)) {
     return value.map((v) => {
-      if (typeof v === 'number') return v
+      if (typeof v === 'number') return v;
       if (typeof v === 'string') {
-        const num = parseFloat(v)
-        return isNaN(num) ? 0 : num
+        const num = parseFloat(v);
+        return isNaN(num) ? 0 : num;
       }
-      return 0
-    }) as [number, number] | [number, number, number, number]
+      return 0;
+    }) as [number, number] | [number, number, number, number];
   }
-  return undefined
+  return undefined;
 }