@zseven-w/pen-core 0.6.0 → 0.7.0

package/src/layout/unwrap-fake-phone-mockup.ts

@@ -0,0 +1,147 @@
+import type { PenNode } from '@zseven-w/pen-types';
+
+/**
+ * Detect and repair "fake phone mockup" frames — frames that look like a
+ * phone mockup (cornerRadius 28-40 + width 240-320, or literally named
+ * "Phone Mockup") but are stuffed with multiple children or use a horizontal/
+ * vertical layout. A genuine phone mockup is `ONE` frame with at most one
+ * placeholder child and `layout: 'none'`.
+ *
+ * Failure mode this addresses: weaker AI sub-agents (M2 family, GLM, Kimi)
+ * sometimes read a generic "Phone mockup = ONE frame, cornerRadius 32" prompt
+ * fragment and apply those visual properties to their own root frame, then
+ * shove the entire section content inside. The resulting wrapper has a
+ * 260px-wide horizontal layout that compresses every section into a 40px
+ * column — visually a complete mess (see 2026-04-06 health-tracker case).
+ *
+ * Two recovery modes:
+ *
+ * 1. **Unwrap (preferred)** — when the fake wrapper is a CHILD of `node`, we
+ *    drop it and promote its children up one level. Visual styling is
+ *    discarded along with the wrapper.
+ *
+ * 2. **Sanitize (fallback)** — when `node` ITSELF is the fake wrapper (the
+ *    sub-agent's own root frame is the fake; we have no parent in scope),
+ *    we strip the phone bezel visuals (cornerRadius, fixed width, layout) and
+ *    rename it. Children stay; they may be duplicates, but at least they
+ *    render in a normal vertical stack instead of being crushed into a 260px
+ *    horizontal column.
+ *
+ * Returns `true` if any node was mutated. Callers operating on store-owned
+ * nodes MUST publish a Zustand update when this returns true — the in-place
+ * mutation does not by itself notify subscribers, so canvas would otherwise
+ * keep showing the old (fake-mockup) state until something else triggered a
+ * store write.
+ */
+export function unwrapFakePhoneMockups(node: PenNode): boolean {
+  let changed = false;
+
+  // Mode (2): self-sanitize if the root itself is the fake wrapper.
+  if (isFakePhoneMockup(node)) {
+    sanitizeFakePhoneMockupRoot(node);
+    changed = true;
+  }
+
+  if (!('children' in node) || !Array.isArray(node.children)) return changed;
+
+  // Mode (1): drop fake wrappers among the children, promote their content.
+  const newChildren: PenNode[] = [];
+  let unwrappedAnyChild = false;
+  for (const child of node.children) {
+    if (isFakePhoneMockup(child)) {
+      const grandchildren =
+        ('children' in child && Array.isArray(child.children) ? child.children : []) ?? [];
+      for (const gc of grandchildren) newChildren.push(gc);
+      unwrappedAnyChild = true;
+    } else {
+      newChildren.push(child);
+    }
+  }
+  if (unwrappedAnyChild) {
+    node.children = newChildren;
+    changed = true;
+  }
+
+  // Recurse into the (possibly updated) children. Promoted grandchildren are
+  // visited too — if a fake mockup wrapped another fake mockup, both are
+  // handled in a single pass.
+  for (const child of node.children) {
+    if (unwrapFakePhoneMockups(child)) {
+      changed = true;
+    }
+  }
+
+  return changed;
+}
+
+/**
+ * Strip phone bezel visual signature from a frame in place. Used when the
+ * frame itself is the fake wrapper and we cannot detach it from a parent.
+ */
+function sanitizeFakePhoneMockupRoot(node: PenNode): void {
+  const rec = node as PenNode & {
+    name?: string;
+    cornerRadius?: unknown;
+    width?: unknown;
+    height?: unknown;
+    layout?: 'none' | 'vertical' | 'horizontal';
+    fill?: unknown;
+  };
+  // Drop misleading visuals
+  delete rec.cornerRadius;
+  // Restore a sensible container width — fill_container lets the parent's
+  // layout decide actual width instead of locking us at 260px.
+  rec.width = 'fill_container';
+  // Drop the fixed bezel height; let content drive intrinsic height.
+  rec.height = 'fit_content';
+  // Force vertical so children stack instead of getting compressed
+  // horizontally inside a fake bezel.
+  rec.layout = 'vertical';
+  // Clear the misleading "Phone Mockup" name so downstream role inference
+  // doesn't act on it.
+  if (typeof rec.name === 'string' && /phone\s*mockup|app\s*mockup/i.test(rec.name)) {
+    rec.name = 'Section';
+  }
+}
+
+function isFakePhoneMockup(node: PenNode): boolean {
+  if (node.type !== 'frame') return false;
+  if (!('children' in node) || !Array.isArray(node.children)) return false;
+
+  // Detection signal #1: literal name match. Models often copy the prompt's
+  // wording verbatim into the node name.
+  const name = (node.name ?? '').toLowerCase();
+  const hasPhoneName = /phone\s*mockup|app\s*mockup|手机\s*样机|手机\s*模型|device\s*frame/.test(
+    name,
+  );
+
+  // Detection signal #2: visual signature. The combination of large radius
+  // (>= 28) and narrow width (240-320) is the classic phone bezel.
+  const cornerR = readCornerRadius(node);
+  const widthNum = typeof node.width === 'number' ? node.width : null;
+  const hasPhoneShape =
+    cornerR != null &&
+    cornerR >= 28 &&
+    cornerR <= 40 &&
+    widthNum != null &&
+    widthNum >= 240 &&
+    widthNum <= 320;
+
+  if (!hasPhoneName && !hasPhoneShape) return false;
+
+  // A real phone mockup is ONE frame with at most one placeholder child and
+  // `layout: 'none'` (or layout unset). Anything more elaborate is a sub-agent
+  // mistake.
+  const childCount = node.children.length;
+  const layout = (node as PenNode & { layout?: string }).layout;
+  const tooManyChildren = childCount > 1;
+  const wrongLayout = layout === 'horizontal' || layout === 'vertical';
+  return tooManyChildren || wrongLayout;
+}
+
+function readCornerRadius(node: PenNode): number | null {
+  const cr = (node as PenNode & { cornerRadius?: number | number[] }).cornerRadius;
+  if (typeof cr === 'number') return cr;
+  if (Array.isArray(cr) && cr.length > 0 && typeof cr[0] === 'number') return cr[0];
+  return null;
+}

package/src/merge/index.ts

@@ -0,0 +1,16 @@
+// packages/pen-core/src/merge/index.ts
+//
+// Public surface for the merge module.
+
+export type { NodePatch } from './node-diff.js';
+export { diffDocuments } from './node-diff.js';
+
+export type {
+  MergeInput,
+  MergeResult,
+  NodeConflict,
+  NodeConflictReason,
+  DocFieldConflict,
+  DocFieldName,
+} from './node-merge.js';
+export { mergeDocuments } from './node-merge.js';

package/src/merge/merge-helpers.ts

@@ -0,0 +1,113 @@
+// packages/pen-core/src/merge/merge-helpers.ts
+//
+// Pure indexing and walking utilities shared by node-diff.ts and node-merge.ts.
+// Not exported from the module's public surface — these are internal helpers.
+
+import type { PenDocument, PenNode } from '@zseven-w/pen-types';
+
+/**
+ * Information stored per indexed node, capturing both the node itself and
+ * the structural context that the merge algorithm needs (page, parent, index).
+ */
+export interface IndexedNode {
+  /** null for legacy single-page documents (no pages array) */
+  pageId: string | null;
+  /** null when the node sits at the top of a page (or top of legacy children) */
+  parentId: string | null;
+  /** position within parent.children (or top-level array) */
+  index: number;
+  node: PenNode;
+}
+
+/**
+ * Walk a document and produce a Map<nodeId, IndexedNode>. Handles both
+ * `pages` and legacy `children` shapes uniformly.
+ */
+export function indexNodesById(doc: PenDocument): Map<string, IndexedNode> {
+  const out = new Map<string, IndexedNode>();
+  for (const page of getAllPages(doc)) {
+    walk(page.children, page.id, null, out);
+  }
+  return out;
+}
+
+function walk(
+  nodes: PenNode[],
+  pageId: string | null,
+  parentId: string | null,
+  out: Map<string, IndexedNode>,
+): void {
+  nodes.forEach((node, index) => {
+    out.set(node.id, { pageId, parentId, index, node });
+    const children = (node as { children?: PenNode[] }).children;
+    if (children && children.length > 0) {
+      walk(children, pageId, node.id, out);
+    }
+  });
+}
+
+/**
+ * Normalize a document into a list of pages, regardless of whether it uses
+ * the explicit `pages` array or the legacy `children` array. Legacy mode
+ * produces a single synthetic page with `id = null`.
+ */
+export function getAllPages(doc: PenDocument): Array<{ id: string | null; children: PenNode[] }> {
+  if (doc.pages && doc.pages.length > 0) {
+    return doc.pages.map((p) => ({ id: p.id, children: p.children }));
+  }
+  return [{ id: null, children: doc.children ?? [] }];
+}
+
+/**
+ * Compare two nodes by atomic fields only (everything except `children`).
+ * Returns true if they would produce the same fields-only diff.
+ */
+export function nodeFieldsEqual(a: PenNode, b: PenNode): boolean {
+  const aFields = stripChildren(a);
+  const bFields = stripChildren(b);
+  return jsonEqual(aFields, bFields);
+}
+
+/**
+ * Return a shallow copy of `node` with the `children` field removed.
+ * Used everywhere we want to compare or diff a node's atomic fields without
+ * the recursive children noise.
+ */
+export function stripChildren<T extends PenNode>(node: T): Omit<T, 'children'> {
+  // Use destructuring; TS-safe.
+  const copy = { ...node } as T & { children?: unknown };
+  delete copy.children;
+  return copy as Omit<T, 'children'>;
+}
+
+/**
+ * Deep value-equality via JSON canonicalization. Used by nodeFieldsEqual and
+ * by the doc-field merge for comparing variable values, theme entries, etc.
+ *
+ * Important: this is intentionally simple. PenNode field values are JSON-safe
+ * (numbers, strings, booleans, plain objects, arrays). No Dates, Maps, Sets,
+ * functions, etc. live in PenDocument.
+ */
+export function jsonEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== 'object') return false;
+  // Both are non-null objects (or arrays)
+  return JSON.stringify(canonicalize(a)) === JSON.stringify(canonicalize(b));
+}
+
+/**
+ * Sort object keys recursively so JSON.stringify produces a deterministic string
+ * regardless of insertion order.
+ */
+function canonicalize(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(canonicalize);
+  const sortedKeys = Object.keys(value as Record<string, unknown>).sort();
+  const out: Record<string, unknown> = {};
+  for (const key of sortedKeys) {
+    out[key] = canonicalize((value as Record<string, unknown>)[key]);
+  }
+  return out;
+}

package/src/merge/node-diff.ts

@@ -0,0 +1,123 @@
+// packages/pen-core/src/merge/node-diff.ts
+//
+// One-direction diff: compute the patches needed to transform `base` into `next`.
+
+import type { PenNode, PenDocument } from '@zseven-w/pen-types';
+import { indexNodesById, nodeFieldsEqual, stripChildren, jsonEqual } from './merge-helpers.js';
+
+export interface NodePatch {
+  op: 'add' | 'remove' | 'modify' | 'move';
+  /** null for legacy single-page documents (no pages array) */
+  pageId: string | null;
+  nodeId: string;
+  /** for `add` / `move`: target parent id; null = top-level on the page */
+  parentId?: string | null;
+  /** for `add` / `move`: target index within parent's children */
+  index?: number;
+  /** for `modify`: only the atomic fields that changed (never includes `children`) */
+  fields?: Partial<PenNode>;
+  /** for `modify`: pre-change values of those same fields, used by 3-way merge */
+  beforeFields?: Partial<PenNode>;
+}
+
+/**
+ * Compute the patches needed to transform `base` into `next`. Walks both trees
+ * by node id and emits one of `add` / `remove` / `modify` / `move` per change.
+ *
+ * Algorithm:
+ *   1. Index both documents by node id.
+ *   2. For each id in base ∪ next:
+ *      - in next only → `add`
+ *      - in base only → `remove`
+ *      - in both → check parent/index (if changed → `move`) and atomic fields
+ *        (if any changed → `modify`); a single id may produce both a `move`
+ *        and a `modify`.
+ */
+export function diffDocuments(base: PenDocument, next: PenDocument): NodePatch[] {
+  const baseIdx = indexNodesById(base);
+  const nextIdx = indexNodesById(next);
+  const allIds = new Set<string>([...baseIdx.keys(), ...nextIdx.keys()]);
+  const patches: NodePatch[] = [];
+
+  for (const id of allIds) {
+    const b = baseIdx.get(id);
+    const n = nextIdx.get(id);
+
+    if (!b && n) {
+      // Added.
+      patches.push({
+        op: 'add',
+        pageId: n.pageId,
+        nodeId: id,
+        parentId: n.parentId,
+        index: n.index,
+        fields: stripChildren(n.node) as Partial<PenNode>,
+      });
+      continue;
+    }
+
+    if (b && !n) {
+      // Removed.
+      patches.push({
+        op: 'remove',
+        pageId: b.pageId,
+        nodeId: id,
+      });
+      continue;
+    }
+
+    if (b && n) {
+      // Present in both. Check for `move` (parent or page changed) and `modify`
+      // (atomic fields changed). They are independent — one node may produce
+      // both kinds of patches.
+      const moved = b.parentId !== n.parentId || b.pageId !== n.pageId || b.index !== n.index;
+      if (moved) {
+        patches.push({
+          op: 'move',
+          pageId: n.pageId,
+          nodeId: id,
+          parentId: n.parentId,
+          index: n.index,
+        });
+      }
+      if (!nodeFieldsEqual(b.node, n.node)) {
+        const { changed, before } = diffFields(b.node, n.node);
+        patches.push({
+          op: 'modify',
+          pageId: n.pageId,
+          nodeId: id,
+          fields: changed,
+          beforeFields: before,
+        });
+      }
+    }
+  }
+
+  return patches;
+}
+
+/**
+ * Compute the per-field delta between two nodes. Returns the keys that changed
+ * (in `next`) along with the original values (from `base`). Skips the `children`
+ * field — it's handled separately by the recursive walk.
+ */
+function diffFields(
+  base: PenNode,
+  next: PenNode,
+): { changed: Partial<PenNode>; before: Partial<PenNode> } {
+  const baseStripped = stripChildren(base) as Record<string, unknown>;
+  const nextStripped = stripChildren(next) as Record<string, unknown>;
+  const allKeys = new Set<string>([...Object.keys(baseStripped), ...Object.keys(nextStripped)]);
+  const changed: Record<string, unknown> = {};
+  const before: Record<string, unknown> = {};
+  for (const key of allKeys) {
+    if (!jsonEqual(baseStripped[key], nextStripped[key])) {
+      changed[key] = nextStripped[key];
+      before[key] = baseStripped[key];
+    }
+  }
+  return {
+    changed: changed as Partial<PenNode>,
+    before: before as Partial<PenNode>,
+  };
+}