@gakim-digital/dexter-bridge 0.13.4 → 0.13.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gakim-digital/dexter-bridge",
-  "version": "0.13.4",
+  "version": "0.13.6",
   "description": "Local bridge for InstaWebAI and Dexter — runs Codex, Claude Code, or OpenCode on your machine.",
   "type": "module",
   "bin": {

package/src/framerRequirementContract.js

@@ -67,6 +67,20 @@ export function mergeRequirements(current, next) {
   return [...byId.values()];
 }
 
+// A requirement may name layers its own edit creates by their temporary ids,
+// or a breakpoint copy of one as the breakpoint id followed by that temporary
+// id. Once Framer gives those layers real ids, the requirement names them.
+export function renameRequirementNodes(requirements, renamedIds = {}) {
+  const renames = Object.entries(renamedIds || {}).filter(([from, to]) => from && to && from !== to);
+  if (!renames.length) return requirements;
+  const rename = (id) => {
+    if (renamedIds[id]) return renamedIds[id];
+    const copy = renames.find(([from]) => id.endsWith(from) && /^[A-Za-z0-9_-]{9}$/.test(id.slice(0, -from.length)));
+    return copy ? `${id.slice(0, -copy[0].length)}${copy[1]}` : id;
+  };
+  return requirements.map((item) => ({ ...item, nodeIds: [...new Set(item.nodeIds.map(rename))] }));
+}
+
 function finiteNumber(value) {
   const number = Number(value);
   return Number.isFinite(number) ? number : null;
@@ -140,6 +154,13 @@ function hasContent(value) {
 // descendant cannot satisfy a claim about its parent. A dotted name such as
 // `link.href` or `hoverEffect.opacity` reads the field inside the property's value.
 function propertyValues(node, property) {
+  // Child layers are named by id, name, type, and text, not their settings.
+  if (property === 'children') {
+    const children = Array.isArray(node.children) ? node.children.filter(isRecord) : [];
+    return children.length
+      ? [children.map((child) => ({ id: child.id, name: child.name ?? null, type: child.type, ...(child.text ? { text: child.text } : {}) }))]
+      : [];
+  }
   const values = keyValues(node, property);
   const [head, ...path] = property.split('.');
   if (values.length > 0 || path.length === 0) return values;
@@ -305,27 +326,46 @@ export function summarizeRequirements(requirements, checkResults) {
 }
 
 // Compares two snapshots of layers that had to stay as they were. A snapshot
-// maps a layer id to { name, rect, props } where props is the serialized
-// layer without children and rect is null when Dexter could not measure the
-// layer, so only its settings are compared. Boxes are compared only when both
-// readings came from the same source (the user's editor or Framer MCP).
-export function unchangedViolations(before, after, tolerance = 1) {
+// maps a layer id to { name, origin, rect, props, children } where props is
+// the serialized layer without children, origin is the layer a breakpoint or
+// variant copy follows, rect is null when Dexter could not measure the layer,
+// so only its settings are compared, and children lists its child layers in
+// order as { id, name, origin }. Sizes are compared only when both readings
+// came from the same source (the user's editor or Framer MCP), and only size
+// counts, not position: a section that grows moves every section below it.
+// The order of child layers does count: a layer inserted without an index
+// lands at the end of its parent.
+// A change is edited when the run edited the layer, the layer it follows, or
+// for a new order one of the child layers; any other change happened without
+// the model touching the layer.
+function childOrder(layer) {
+  return layer.children.map((child) => child.id).join(',');
+}
+
+export function unchangedViolations(before, after, edited = new Set(), tolerance = 1) {
   const changes = [];
   for (const [id, earlier] of Object.entries(before || {})) {
     const later = after?.[id];
     const name = earlier.name || id;
-    if (!later) {
-      changes.push(`${name} was removed`);
-      continue;
-    }
+    const editedLayer = (layer) => edited.has(layer.id) || Boolean(layer.origin && edited.has(layer.origin));
+    let source = edited.has(id) ? 'self' : earlier.origin && edited.has(earlier.origin) ? 'origin' : null;
     const a = earlier.rect;
-    const b = later.rect;
+    const b = later?.rect;
     const comparable = a && b && (a.source || null) === (b.source || null);
-    if (comparable && ['x', 'y', 'width', 'height'].some((key) => Math.abs(a[key] - b[key]) > tolerance)) {
-      changes.push(`${name} moved or resized (${a.width}×${a.height} at ${a.x},${a.y} → ${b.width}×${b.height} at ${b.x},${b.y})`);
-    } else if (earlier.props !== later.props) {
-      changes.push(`${name} has different settings`);
-    }
+    let text = null;
+    if (!later) text = `${name} was removed`;
+    else if (comparable && ['width', 'height'].some((key) => Math.abs(a[key] - b[key]) > tolerance)) {
+      text = `${name} changed size (${a.width}×${a.height} → ${b.width}×${b.height})`;
+    } else if (earlier.children && later.children && childOrder(earlier) !== childOrder(later)) {
+      text = `${name} now holds its layers in this order: ${later.children.slice(0, 12).map((child) => child.name || child.id).join(', ')}`;
+      if (!source && [...earlier.children, ...later.children].some(editedLayer)) source = 'children';
+    } else if (earlier.props !== later.props) text = `${name} has different settings`;
+    const note = source === 'self'
+      ? ' (you edited it)'
+      : source === 'origin'
+        ? ` (it follows your edit of ${earlier.origin})`
+        : source === 'children' ? ' (you edited layers inside it)' : '';
+    if (text) changes.push({ text: `${text}${note}`, edited: Boolean(source) });
     if (changes.length >= 20) break;
   }
   return changes;

package/src/framerTools.js

@@ -9,6 +9,7 @@ import {
   normalizeChecks,
   normalizeRequirements,
   summarizeRequirements,
+  renameRequirementNodes,
   unchangedViolations,
   verifyChecks,
 } from './framerRequirementContract.js';
@@ -76,7 +77,7 @@ const CHECK_SCHEMA = {
   properties: {
     requirementId: { type: 'string' },
     nodeId: { type: 'string' },
-    property: { type: 'string', description: 'A Framer property to read, such as fill, link.href, or text. Use either property or measure.' },
+    property: { type: 'string', description: 'A Framer property to read, such as fill, link.href, or text; children lists the child layers of the layer by name. Use either property or measure.' },
     contains: { type: 'string', description: 'Text the property value must contain, such as #151515 or /contact.' },
     absent: { type: 'boolean', description: 'True when the requirement is that the property is not set on the layer, such as no appearEffect on a background image.' },
     measure: { type: 'string', enum: MEASURES, description: 'width, height, gap (to otherNodeId), or insideParent (the layer stays inside its parent).' },
@@ -789,10 +790,15 @@ function helpersUsed(program) {
 
 // Reads what framer_verify needs in one program: the layers whose properties
 // are checked, and each measure in order.
-export function verifyProgram(propertyNodeIds, measures) {
+// Layers whose checks name children are read one level deep so their
+// child layers can be checked.
+export function verifyProgram(propertyNodeIds, measures, childNodeIds = []) {
   return `${MEASURE_PRELUDE}
 const tree = api.tree;
-const nodes = await tree.serializeNodes(${JSON.stringify(propertyNodeIds)}, { depth: 0 });
+const withChildren = new Set(${JSON.stringify(childNodeIds)});
+const flat = await tree.serializeNodes(${JSON.stringify(propertyNodeIds)}.filter((id) => !withChildren.has(id)), { depth: 0 });
+const nested = withChildren.size ? await tree.serializeNodes([...withChildren], { depth: 1 }) : [];
+const nodes = [...(flat || []), ...(nested || [])];
 const measured = [];
 for (const check of ${JSON.stringify(measures)}) {
   try {
@@ -824,8 +830,9 @@ return { nodes, measured };`;
 }
 
 // Records layers the user wants left as they are: each layer's measured box,
-// when Framer has laid it out, and a fingerprint of its settings, for every
-// layer inside them.
+// when Framer has laid it out, a fingerprint of its settings, and the layer a
+// breakpoint or variant copy follows, for every layer inside them. The read
+// after the run passes walk: false to read back exactly the recorded layers.
 // Layers name colour styles only as var(--token-id). Reads carry the style's
 // name and values next to them, so a model can tell a dark page colour from
 // a light surface without guessing from the id.
@@ -851,14 +858,16 @@ export function describeColorStyle(style) {
   return `${style?.name || 'Unnamed colour style'}${values ? ` (${values})` : ''}`;
 }
 
-export function snapshotProgram(rootIds) {
+export function snapshotProgram(rootIds, { walk = true } = {}) {
   return `${LAYOUT_CHECK}
 const tree = api.tree;
 const fingerprint = (text) => { let hash = 2166136261; for (let i = 0; i < text.length; i += 1) { hash ^= text.charCodeAt(i); hash = Math.imul(hash, 16777619); } return (hash >>> 0).toString(36); };
 const ids = new Set();
 for (const root of ${JSON.stringify(rootIds)}) {
+  if (${walk ? 'true' : 'false'} && ids.size >= ${UNCHANGED_LAYER_LIMIT}) break;
   if (!tree.get(root)) continue;
   ids.add(root);
+  if (!${walk ? 'true' : 'false'}) continue;
   for (const node of tree.walk(root)) {
     if (ids.size >= ${UNCHANGED_LAYER_LIMIT}) break;
     if (node && node.id) ids.add(node.id);
@@ -871,7 +880,12 @@ for (const id of ids) {
   const rect = (await __dexterLaidOut(id)) ? await __dexterRect(id) : null;
   let props = '';
   try { const { children, ...rest } = JSON.parse(JSON.stringify(node)); props = fingerprint(JSON.stringify(rest)); } catch {}
-  out[id] = { name: node.name || null, rect: rect ? { x: rect.x, y: rect.y, width: rect.width, height: rect.height } : null, props };
+  const children = (Array.isArray(node.children) ? node.children : []).slice(0, 60).map((child) => {
+    const childId = child && typeof child === 'object' ? child.id : child;
+    const childNode = childId ? tree.get(childId) : null;
+    return { id: childId, name: (childNode && childNode.name) || null, origin: (childNode && childNode.$originalId) || null };
+  }).filter((child) => child.id);
+  out[id] = { name: node.name || null, origin: node.$originalId || null, rect: rect ? { x: rect.x, y: rect.y, width: rect.width, height: rect.height } : null, props, children };
 }
 return out;`;
 }
@@ -923,6 +937,7 @@ export function createFramerAgentToolRuntime({
   const unchangedBefore = {};
   let unchangedPending = [];
   let unchangedChanges = [];
+  const weighedPropertyErrors = new Set();
   const colorStyles = new Map();
   let promptContext = {};
   // Set once the panel fails to answer, so a closed panel does not cost a
@@ -974,6 +989,10 @@ export function createFramerAgentToolRuntime({
 
   const client = mcpClient || createFramerMcpClient({ getAccessToken: tokenGetter });
 
+  function propertyErrorKey(error) {
+    return `${error.nodeId}.${error.property}`;
+  }
+
   function lingeringPropertyErrors() {
     let open = [];
     for (const receipt of mutationReceipts) {
@@ -1181,8 +1200,8 @@ export function createFramerAgentToolRuntime({
   // Records the layers the plan said to leave as they are. Boxes come from the
   // editor where it measured them, otherwise from Framer MCP where that page is
   // laid out; each records its source so before and after compare like with like.
-  async function snapshotLayers(roots) {
-    const snapshot = outputOf(await client.exec(snapshotProgram(roots))).result;
+  async function snapshotLayers(roots, options) {
+    const snapshot = outputOf(await client.exec(snapshotProgram(roots, options))).result;
     if (!snapshot || typeof snapshot !== 'object') return null;
     for (const entry of Object.values(snapshot)) if (entry?.rect) entry.rect.source = 'mcp';
     const layers = await measureInEditor(Object.keys(snapshot));
@@ -1328,6 +1347,7 @@ export function createFramerAgentToolRuntime({
         await snapshotUnchanged();
         const result = await client.exec(wrapProgram(program));
         const applied = applyReceipt(result, screenshotNodeIds);
+        requirements = renameRequirementNodes(requirements, applied.receipt.renamedIds);
         const programError = programErrorOf(applied.output, wrappedLineOffset(program));
         // Layers created by this program only get their real ids once it
         // finishes, so screenshots are taken in a second call.
@@ -1417,7 +1437,8 @@ export function createFramerAgentToolRuntime({
         const measures = measureChecks(checks);
         const layers = await measureInEditor(measures.flatMap((check) => [check.nodeId, check.otherNodeId]));
         const fromEditor = measures.map((check) => editorMeasurement(check, layers));
-        const result = await client.exec(verifyProgram(checkNodeIds(checks), measures.filter((_, index) => !fromEditor[index])));
+        const childNodeIds = [...new Set(checks.filter((check) => check.property === 'children').map((check) => check.nodeId))];
+        const result = await client.exec(verifyProgram(checkNodeIds(checks), measures.filter((_, index) => !fromEditor[index]), childNodeIds));
         const output = outputOf(result);
         if (output.error) throw toolError('FRAMER_PROGRAM_FAILED', String(output.error).split('\n')[0].slice(0, 300));
         const { nodes, measured: fromMcp } = output.result && typeof output.result === 'object' ? output.result : {};
@@ -1615,6 +1636,7 @@ export function createFramerAgentToolRuntime({
     const missing = verification().missingChecks;
     const propertyErrors = lingeringPropertyErrors();
     const facts = [];
+    for (const error of propertyErrors) weighedPropertyErrors.add(propertyErrorKey(error));
     if (propertyErrors.length) {
       facts.push(`Framer rejected these properties, so they are not set: ${propertyErrors.map((error) => `${error.nodeId}.${error.property}: ${error.message}`).join('; ')}.`);
     }
@@ -1633,10 +1655,10 @@ export function createFramerAgentToolRuntime({
     }
     const unchecked = uncheckedRequirements();
     if (unchecked.length) {
-      facts.push(`These requirements from your plan have not been checked since your last change, so they are not confirmed either way: ${unchecked.map((item) => item.text).join('; ')}.`);
+      facts.push(`These requirements from your plan have not been checked since your last change, so they are not confirmed either way: ${unchecked.map((item) => `${item.id}: ${item.text}`).join('; ')}.`);
     }
     if (unchangedChanges.length) {
-      facts.push(`These layers you planned to leave as they were now read differently: ${unchangedChanges.join('; ')}.`);
+      facts.push(`These layers you planned to leave as they were now read differently: ${unchangedChanges.map((change) => change.text).join('; ')}.`);
     }
     if (!facts.length) return null;
     return [
@@ -1700,8 +1722,8 @@ export function createFramerAgentToolRuntime({
     if (mutationCalls > 0 && Object.keys(unchangedBefore).length) {
       try {
         await ensureProject();
-        const after = await snapshotLayers(Object.keys(unchangedBefore).slice(0, UNCHANGED_LAYER_LIMIT));
-        unchangedChanges = after ? unchangedViolations(unchangedBefore, after) : [];
+        const after = await snapshotLayers(Object.keys(unchangedBefore), { walk: false });
+        unchangedChanges = after ? unchangedViolations(unchangedBefore, after, known) : [];
         readCalls += 1;
       } catch {
         unchangedChanges = [];
@@ -1739,7 +1761,9 @@ export function createFramerAgentToolRuntime({
         output: 'No layer changed for a summary that claimed a change.',
       });
     }
-    const propertyErrors = lingeringPropertyErrors();
+    // A rejected property the model was shown and then finished without is
+    // its judgment, such as reaching the goal another way.
+    const propertyErrors = lingeringPropertyErrors().filter((error) => !weighedPropertyErrors.has(propertyErrorKey(error)));
     if (propertyErrors.length) {
       checks.push({
         command: PROPERTY_ERROR_CHECK,
@@ -1774,11 +1798,14 @@ export function createFramerAgentToolRuntime({
           .slice(0, 2000),
       });
     }
-    if (unchangedChanges.length) {
+    // A layer the model edited, or one that follows its edit, is a change it
+    // made and weighed; only changes nothing in the run explains fail it.
+    const unexplained = unchangedChanges.filter((change) => !change.edited);
+    if (unexplained.length) {
       checks.push({
         command: UNCHANGED_CHECK,
         status: 'failed',
-        output: unchangedChanges.join('; ').slice(0, 2000),
+        output: unexplained.map((change) => change.text).join('; ').slice(0, 2000),
       });
     }
     // The model's own plan sets the evidence it owes; a run that changed the