@gakim-digital/dexter-bridge 0.13.0 → 0.13.2

package/src/framerTools.js

@@ -2,18 +2,23 @@ import crypto from 'node:crypto';
 import jsTokens from 'js-tokens';
 import { createFramerMcpClient } from './framerMcpClient.js';
 import {
-  evidenceNodeIds,
-  mergeBehaviorPlans,
-  normalizeBehaviorEvidence,
-  normalizeBehaviorPlan,
-  summarizeBehaviorVerification,
-  verifyBehaviorChecks,
-} from './framerBehaviorContract.js';
+  MEASURES,
+  checkNodeIds,
+  measureChecks,
+  mergeRequirements,
+  normalizeChecks,
+  normalizeRequirements,
+  summarizeRequirements,
+  unchangedViolations,
+  verifyChecks,
+} from './framerRequirementContract.js';
 
 export const UNAPPLIED_CHANGE_CHECK = 'Harness change check';
 export const PROPERTY_ERROR_CHECK = 'Unapplied properties';
 export const CLAIMED_TARGET_CHECK = 'Claimed targets';
 export const VERIFICATION_CHECK = 'Harness-owned final verification';
+export const REQUIREMENTS_CHECK = 'Requirements';
+export const UNCHANGED_CHECK = 'Unchanged layers';
 
 const LITERAL_TOKEN_TYPES = new Set(['StringLiteral', 'NoSubstitutionTemplate', 'TemplateHead', 'TemplateMiddle', 'TemplateTail']);
 const UNSAFE_EXEC_PATTERN = /\b(?:process|globalThis|global|require|import\s*\(|child_process|worker_threads|fs|os|net|tls|dgram|http|https|fetch|WebSocket|eval|Function)\b/;
@@ -40,39 +45,61 @@ const MAX_RESULT_CHARS = 6_000;
 // Users judge progress by the canvas, so a run that is still only reading
 // after this long is told to start building.
 const FIRST_EDIT_NUDGE_MS = 60_000;
-const FIRST_EDIT_NUDGE = 'Nothing is on the canvas yet. You know enough to start: make your first framer_edit now with a small first section, such as the navigation and the hero headline, then build the rest two sections per edit. Read more only when a specific detail blocks the next edit.';
+const FIRST_EDIT_NUDGE = 'If this request changes the canvas, nothing is on it yet and you know enough to start: make your first framer_edit now with a small first section, such as the navigation and the hero headline, then build the rest two sections per edit. Read more only when a specific detail blocks the next edit. If the user asked only for an answer or an analysis, keep to that.';
 const FONT_ERROR_HINT = 'A font Framer rejected is not available to this project. Follow the preloaded project APIs guidance: resolve the family through api.fonts before setting it, or use a family the project already uses. Fix it in your next framer_edit, not at the end.';
 const ACTIVE_PAGE_OUTLINE_DEPTH = 2;
 // Framer returns the previous layout for about 50ms after an edit.
 const LAYOUT_SETTLE_MS = 150;
+const UNCHANGED_LAYER_LIMIT = 600;
 const FONT_KEYS = new Set(['font', 'fontFamily', 'family']);
 const PROJECT_MISMATCH_PATTERN = /permission|forbidden|not found|does not have access|no access|can't open|cannot open/i;
 
-const MEASURE_TOOL_NOTE = 'For exact spacing or sizes, await dexter.measure(ids) returns each layer\'s x, y, width, and height inside its breakpoint frame, and await dexter.gap(a, b) returns the vertical and horizontal space between two layers (negative when they share that range) and whether they overlap. Both measure the rendered layout, including edits made earlier in the same program.';
+const MEASURE_TOOL_NOTE = 'For exact spacing or sizes, await dexter.measure(ids) returns each layer\'s x, y, width, and height inside its breakpoint frame, and await dexter.gap(a, b) returns the vertical and horizontal space between two layers (negative when they share that range) and whether they overlap. Both measure the rendered layout, including edits made earlier in the same program. Framer lays out only some pages for Dexter; elsewhere a layer comes back with measured: false, and then there are no numbers to act on, so judge it from a screenshot.';
 
-// Item shapes the behavior contract (framerBehaviorContract.js) accepts.
-const BEHAVIOR_SCHEMA = {
+// Item shapes the requirement contract (framerRequirementContract.js) accepts.
+const REQUIREMENT_SCHEMA = {
   type: 'object',
   properties: {
-    id: { type: 'string', description: 'Short unique id, such as "whatsapp-links".' },
-    description: { type: 'string', description: 'What the user should experience.' },
-    targetNodeIds: { type: 'array', items: { type: 'string' }, description: 'Every node that should carry the behavior.' },
+    id: { type: 'string', description: 'Short unique id, such as "button-height".' },
+    text: { type: 'string', description: 'What must be true, in the user\'s terms, such as "Send Enquiry button is about 52px tall".' },
+    nodeIds: { type: 'array', items: { type: 'string' }, description: 'Every layer that must meet it, when it applies to several.' },
   },
-  required: ['id', 'description'],
+  required: ['id', 'text'],
   additionalProperties: false,
 };
-const BEHAVIOR_CHECK_SCHEMA = {
+const CHECK_SCHEMA = {
   type: 'object',
   properties: {
-    behaviorId: { type: 'string' },
+    requirementId: { type: 'string' },
     nodeId: { type: 'string' },
-    property: { type: 'string', description: 'The Framer property that carries the behavior, such as link.href.' },
-    contains: { type: 'string', description: 'Text the property value must contain.' },
+    property: { type: 'string', description: 'A Framer property to read, such as fill, link.href, or text. 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).' },
+    otherNodeId: { type: 'string' },
+    expected: { type: 'number', description: 'Expected pixels for width, height, or gap.' },
+    tolerance: { type: 'number', description: 'Allowed difference in pixels; defaults to 2.' },
   },
-  required: ['behaviorId', 'nodeId', 'property'],
+  required: ['requirementId', 'nodeId'],
   additionalProperties: false,
 };
 
+// Offered only when the Dexter panel says it can measure: it reads the page
+// open in the user's editor, which Framer lays out, unlike most pages Dexter
+// reads through Framer MCP.
+const FRAMER_MEASURE_DEFINITION = {
+  name: 'framer_measure',
+  description: 'Measure layers on the page open in the user\'s Framer editor: each layer\'s x, y, width, and height inside its breakpoint frame, and its box inside its parent. It reads the editor\'s own layout, on every breakpoint of that page, including your latest edits. Layers on other pages come back measured: false. Use it when dexter.measure returns measured: false.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      nodeIds: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 100 },
+    },
+    required: ['nodeIds'],
+    additionalProperties: false,
+  },
+};
+
 const TOOL_DEFINITIONS = [
   {
     name: 'framer_read',
@@ -97,14 +124,14 @@ const TOOL_DEFINITIONS = [
         screenshotNodeIds: { type: 'array', items: { type: 'string' }, maxItems: 4 },
         plan: {
           type: 'object',
-          description: 'Your task plan, on the first framer_edit: a summary, the task domains, and the evidence you will produce (for example structural, visual, interactions). For interactive or animated results, list each behavior with every node that should carry it.',
+          description: 'Your task plan, on the first framer_edit. requirements lists every concrete, checkable thing the request asks for: values, colours, sizes, spacing, text, links, order, visibility, and behaviors, each with the layers it applies to. unchanged lists layers the user wants left exactly as they are, such as other breakpoints when they named one; Dexter records them before this edit and compares them at the end. verification lists other evidence you will produce, such as visual.',
           properties: {
             summary: { type: 'string' },
-            domains: { type: 'array', items: { type: 'string' } },
+            requirements: { type: 'array', items: REQUIREMENT_SCHEMA },
+            unchanged: { type: 'array', items: { type: 'string' }, maxItems: 20 },
             verification: { type: 'array', items: { type: 'string' } },
-            behaviors: { type: 'array', items: BEHAVIOR_SCHEMA },
           },
-          required: ['summary', 'domains', 'verification'],
+          required: ['summary', 'requirements'],
           additionalProperties: false,
         },
       },
@@ -137,13 +164,13 @@ const TOOL_DEFINITIONS = [
     },
   },
   {
-    name: 'framer_verify_interactions',
-    description: 'Check that each declared behavior sits on the node properties you name. This is structural evidence, not runtime playback.',
+    name: 'framer_verify',
+    description: 'Check your plan\'s requirements against the live project after your last change. Each check names a requirement and a layer, and either a property to read (optionally with text its value must contain, or absent when it must not be set) or a measure: width, height, gap to another layer, or insideParent. Dexter reads Framer and returns which requirements are met. A requirement counts only when every layer it names passes. A measure Dexter cannot take on this page comes back unmeasured: that is not a failure, and there is nothing to fix; judge it from a screenshot when it matters.',
     inputSchema: {
       type: 'object',
       properties: {
-        checks: { type: 'array', items: BEHAVIOR_CHECK_SCHEMA },
-        behaviors: { type: 'array', items: BEHAVIOR_SCHEMA },
+        checks: { type: 'array', items: CHECK_SCHEMA },
+        requirements: { type: 'array', items: REQUIREMENT_SCHEMA, description: 'Requirements to add to your plan before checking.' },
       },
       required: ['checks'],
       additionalProperties: false,
@@ -352,10 +379,98 @@ function outputOf(result) {
   return structured.output && typeof structured.output === 'object' ? structured.output : structured;
 }
 
+const BASE64_PATTERN = /^[A-Za-z0-9+/]+={0,2}$/;
+const DATA_URL_PATTERN = /^data:(image\/[a-z0-9.+-]+);base64,(.+)$/is;
+const IMAGE_FETCH_TIMEOUT_MS = 15_000;
+const MAX_MODEL_IMAGE_BYTES = 8 * 1024 * 1024;
+
+// Models accept images only as inline base64 data. Framer returns screenshots
+// as links, and a program may hand back a data URL; both become plain base64,
+// and anything else is dropped rather than sent on.
+async function modelReadyImage(image, fetchImpl = fetch) {
+  const raw = typeof image?.data === 'string' ? image.data.trim() : '';
+  const mimeType = image?.mimeType || 'image/png';
+  if (!raw) return null;
+  const dataUrl = raw.match(DATA_URL_PATTERN);
+  if (dataUrl) return { mimeType: dataUrl[1], data: dataUrl[2].replace(/\s+/g, '') };
+  if (/^https:\/\//i.test(raw)) {
+    try {
+      const response = await fetchImpl(raw, { signal: AbortSignal.timeout(IMAGE_FETCH_TIMEOUT_MS) });
+      const type = String(response.headers.get('content-type') || '').split(';')[0].trim();
+      if (!response.ok || !type.startsWith('image/')) return null;
+      const bytes = Buffer.from(await response.arrayBuffer());
+      if (!bytes.length || bytes.length > MAX_MODEL_IMAGE_BYTES) return null;
+      return { mimeType: type, data: bytes.toString('base64') };
+    } catch {
+      return null;
+    }
+  }
+  const compact = raw.replace(/\s+/g, '');
+  if (!BASE64_PATTERN.test(compact)) return null;
+  const type = imageTypeOf(Buffer.from(compact.slice(0, 32), 'base64'));
+  return type ? { mimeType: type, data: compact } : null;
+}
+
+function imageTypeOf(bytes) {
+  if (bytes.length >= 4 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) return 'image/png';
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'image/jpeg';
+  if (bytes.length >= 4 && bytes.toString('ascii', 0, 4) === 'GIF8') return 'image/gif';
+  if (bytes.length >= 12 && bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP') return 'image/webp';
+  return null;
+}
+
+// Width and height from a PNG or JPEG header.
+export function imageSize(bytes) {
+  if (bytes.length >= 24 && bytes[0] === 0x89 && bytes.toString('ascii', 1, 4) === 'PNG') {
+    return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+  }
+  if (bytes.length >= 4 && bytes[0] === 0xff && bytes[1] === 0xd8) {
+    let offset = 2;
+    while (offset + 9 < bytes.length) {
+      if (bytes[offset] !== 0xff) { offset += 1; continue; }
+      const marker = bytes[offset + 1];
+      const length = bytes.readUInt16BE(offset + 2);
+      if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) {
+        return { width: bytes.readUInt16BE(offset + 7), height: bytes.readUInt16BE(offset + 5) };
+      }
+      offset += 2 + length;
+    }
+  }
+  return null;
+}
+
+// What the editor's measurement of one layer says for a measure check:
+// { value }, { inside, overflow }, or null when the editor did not measure it.
+export function editorMeasurement(check, layers) {
+  const layer = layers?.[check.nodeId];
+  if (!layer?.measured) return null;
+  if (check.measure === 'width' || check.measure === 'height') return { value: layer[check.measure] };
+  if (check.measure === 'insideParent') {
+    const rect = layer.rect;
+    const parent = layer.parent;
+    if (!rect || !parent) return null;
+    const overflow = Math.max(0, -rect.x, -rect.y, rect.x + rect.width - parent.width, rect.y + rect.height - parent.height);
+    return { inside: overflow <= check.tolerance, overflow: Math.round(overflow) };
+  }
+  if (check.measure === 'gap') {
+    const other = layers?.[check.otherNodeId];
+    if (!other?.measured || other.frameId !== layer.frameId) return null;
+    const vertical = Math.max(other.y - (layer.y + layer.height), layer.y - (other.y + other.height));
+    const horizontal = Math.max(other.x - (layer.x + layer.width), layer.x - (other.x + other.width));
+    return { value: vertical >= 0 ? vertical : horizontal >= 0 ? horizontal : Math.max(vertical, horizontal) };
+  }
+  return null;
+}
+
+export async function modelReadyImages(images, fetchImpl = fetch) {
+  const ready = await Promise.all((images || []).map((image) => modelReadyImage(image, fetchImpl)));
+  return ready.filter(Boolean);
+}
+
 function imagesFromExec(result, output) {
   const listed = Array.isArray(output?.images) ? output.images : [];
   const fromOutput = listed.flatMap((image) => {
-    const data = image?.data || image?.base64;
+    const data = image?.data || image?.base64 || image?.url;
     if (typeof data !== 'string' || !data) return [];
     return [{ mimeType: image.mimeType || image.mediaType || 'image/png', data }];
   });
@@ -450,12 +565,46 @@ const __dexterApi = __dexterRecording(api, {}, {
 });
 `;
 
+// Framer MCP lays out only some pages. On the others getRect returns
+// placeholder boxes: a layer sized by its parent or content reads 200px and
+// can sit centred on its own origin (x = -width/2, y = -height/2), and the
+// numbers change between reads. A reading counts only when the layer and every
+// layer above it, up to its breakpoint, look laid out.
+const LAYOUT_CHECK = `
+const __dexterRelative = (value) => value == null || !/px$/.test(String(value));
+const __dexterUnlaid = (node, rect) => {
+  if (!rect) return true;
+  if ((rect.width > 0 || rect.height > 0) && Math.abs(rect.x + rect.width / 2) < 0.5 && Math.abs(rect.y + rect.height / 2) < 0.5) return true;
+  if (__dexterRelative(node && node.width) && Math.abs(rect.width - 200) < 0.01) return true;
+  if (__dexterRelative(node && node.height) && Math.abs(rect.height - 200) < 0.01) return true;
+  return false;
+};
+const __dexterRects = new Map();
+const __dexterRect = async (id) => {
+  if (!__dexterRects.has(id)) __dexterRects.set(id, await api.tree.getRect(id));
+  return __dexterRects.get(id);
+};
+const __dexterLaidOut = async (id) => {
+  const node = api.tree.get(id);
+  if (!node) return false;
+  const frame = await api.tree.getGroundNodeFor(id);
+  if (__dexterUnlaid(node, await __dexterRect(id))) return false;
+  if (frame && frame.id === id) return true;
+  for (const ancestor of (await api.tree.getAncestorsFor(id)) || []) {
+    if (frame && ancestor.id === frame.id) break;
+    if (__dexterUnlaid(ancestor, await __dexterRect(ancestor.id))) return false;
+  }
+  return true;
+};
+const __dexterUnmeasuredNote = 'Framer has not laid out this page for Dexter, so this layer\\'s size and position cannot be read here. Judge it by eye instead.';
+`;
+
 // Programs get `dexter.measure` and `dexter.gap` for exact spacing and sizes.
 // Framer's getRect is relative to the parent, so positions are summed up to
 // the breakpoint (or variant) frame, which keeps desktop and phone apart.
 // Layout settles shortly after an edit; measuring straight away returns the
 // old layout, so each call waits first.
-const MEASURE_PRELUDE = `
+const MEASURE_PRELUDE = `${LAYOUT_CHECK}
 // Layers inserted by this program are known to Framer only by their real ids
 // until the program ends; the edit recorder maps the program's own ids.
 const __dexterInsertedIds = {};
@@ -465,13 +614,14 @@ const dexter = (() => {
     const id = typeof value === 'string' ? value : (value && typeof value.id === 'string' ? value.id : null);
     return (id && __dexterInsertedIds[id]) || id;
   };
-  const settle = () => new Promise((resolve) => setTimeout(resolve, ${LAYOUT_SETTLE_MS}));
+  const settle = () => new Promise((resolve) => setTimeout(resolve, ${LAYOUT_SETTLE_MS})).then(() => __dexterRects.clear());
   const one = async (value) => {
     const id = idOf(value);
     const node = id ? tree.get(id) : null;
     if (!node) return { id, measured: false, note: 'Framer has no layer with this id.' };
     const rect = await tree.getRect(id);
     if (!rect) return { id, measured: false };
+    if (!(await __dexterLaidOut(id))) return { id, name: node.name || null, measured: false, unmeasured: true, note: __dexterUnmeasuredNote };
     const frame = await tree.getGroundNodeFor(id);
     let x = rect.x;
     let y = rect.y;
@@ -497,7 +647,10 @@ const dexter = (() => {
     async gap(first, second) {
       await settle();
       const [a, b] = await measureAll([first, second]);
-      if (a.measured === false || b.measured === false) return { a, b, measured: false };
+      if (a.measured === false || b.measured === false) {
+        const unmeasured = a.unmeasured === true || b.unmeasured === true;
+        return { a, b, measured: false, ...(unmeasured ? { unmeasured: true, note: __dexterUnmeasuredNote } : {}) };
+      }
       if (a.frame?.id !== b.frame?.id) return { a, b, measured: false, note: 'These layers are in different breakpoints or frames.' };
       const vertical = Math.max(b.y - (a.y + a.height), a.y - (b.y + b.height));
       const horizontal = Math.max(b.x - (a.x + a.width), a.x - (b.x + b.width));
@@ -624,6 +777,76 @@ return verdicts;
 `;
 }
 
+// Which Dexter helpers a program uses, kept on the call record so runs show
+// whether models measure.
+function helpersUsed(program) {
+  return ['measure', 'gap'].filter((name) => program.includes(`dexter.${name}`));
+}
+
+// Reads what framer_verify needs in one program: the layers whose properties
+// are checked, and each measure in order.
+export function verifyProgram(propertyNodeIds, measures) {
+  return `${MEASURE_PRELUDE}
+const tree = api.tree;
+const nodes = await tree.serializeNodes(${JSON.stringify(propertyNodeIds)}, { depth: 0 });
+const measured = [];
+for (const check of ${JSON.stringify(measures)}) {
+  try {
+    if (check.measure === 'insideParent') {
+      const rect = await tree.getRect(check.nodeId);
+      const parent = await tree.getParentNodeFor(check.nodeId);
+      const box = parent ? await tree.getRect(parent.id) : null;
+      if (!rect || !box) { measured.push({ error: check.nodeId + ' or its parent could not be measured' }); continue; }
+      if (!(await __dexterLaidOut(check.nodeId)) || !(await __dexterLaidOut(parent.id))) { measured.push({ unmeasured: true, note: __dexterUnmeasuredNote }); continue; }
+      const overflow = Math.max(0, -rect.x, -rect.y, rect.x + rect.width - box.width, rect.y + rect.height - box.height);
+      measured.push({ inside: overflow <= check.tolerance, overflow: Math.round(overflow) });
+    } else if (check.measure === 'gap') {
+      const space = await dexter.gap(check.nodeId, check.otherNodeId);
+      if (space.unmeasured) { measured.push({ unmeasured: true, note: space.note }); continue; }
+      if (space.measured === false) { measured.push({ error: space.note || 'these layers could not be measured' }); continue; }
+      const value = space.vertical >= 0 ? space.vertical : space.horizontal >= 0 ? space.horizontal : Math.max(space.vertical, space.horizontal);
+      measured.push({ value });
+    } else {
+      const [box] = await dexter.measure([check.nodeId]);
+      if (box.unmeasured) { measured.push({ unmeasured: true, note: box.note }); continue; }
+      if (box.measured === false) { measured.push({ error: box.note || check.nodeId + ' could not be measured' }); continue; }
+      measured.push({ value: box[check.measure] });
+    }
+  } catch (error) {
+    measured.push({ error: String((error && error.message) || error).slice(0, 200) });
+  }
+}
+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.
+export function snapshotProgram(rootIds) {
+  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 (!tree.get(root)) continue;
+  ids.add(root);
+  for (const node of tree.walk(root)) {
+    if (ids.size >= ${UNCHANGED_LAYER_LIMIT}) break;
+    if (node && node.id) ids.add(node.id);
+  }
+}
+const out = {};
+for (const id of ids) {
+  const node = tree.get(id);
+  if (!node) continue;
+  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 };
+}
+return out;`;
+}
+
 function mismatchMessage(name) {
   const account = name ? ` (${name})` : '';
   return `Your connected Framer account${account} can't open this project — connect the account that owns it.`;
@@ -634,9 +857,11 @@ export function createFramerAgentToolRuntime({
   onActivity,
   authorizeProject,
   readWebsite,
+  callPanelTool,
   mcpClient,
   getAccessToken,
   trace,
+  fetchImpl = fetch,
 } = {}) {
   const context = assignment?.context && typeof assignment.context === 'object' ? assignment.context : {};
   const projectId = String(context.framerProjectId || '').trim();
@@ -646,7 +871,13 @@ export function createFramerAgentToolRuntime({
   const allowedTools = Array.isArray(assignment?.toolProtocol?.tools)
     ? new Set(assignment.toolProtocol.tools)
     : null;
-  const definitions = TOOL_DEFINITIONS.filter((tool) => !allowedTools || allowedTools.has(tool.name));
+  const editorMeasures = typeof callPanelTool === 'function'
+    && Array.isArray(context.panelTools)
+    && context.panelTools.includes('framer_measure');
+  const definitions = [
+    ...TOOL_DEFINITIONS.filter((tool) => !allowedTools || allowedTools.has(tool.name)),
+    ...(editorMeasures ? [FRAMER_MEASURE_DEFINITION] : []),
+  ];
   const reportActivity = typeof onActivity === 'function' ? onActivity : () => undefined;
 
   let framerUserName = null;
@@ -657,8 +888,16 @@ export function createFramerAgentToolRuntime({
   let readCalls = 0;
   let toolCallCount = 0;
   let plan = null;
-  let behaviorPlan = null;
-  let behaviorResults = [];
+  let requirements = [];
+  // Latest check result per requirement, each stamped with when it was read.
+  let checkResults = [];
+  const unchangedBefore = {};
+  let unchangedPending = [];
+  let unchangedChanges = [];
+  let promptContext = {};
+  // Set once the panel fails to answer, so a closed panel does not cost a
+  // wait on every later measure.
+  let editorMeasureUnavailable = false;
   let lastMutationAt = 0;
   let lastReadAfterMutationAt = 0;
   let lastVisualAt = 0;
@@ -814,6 +1053,7 @@ export function createFramerAgentToolRuntime({
       }));
     const failedCalls = calls(inner.dexterFailed);
     const receipt = {
+      kind: 'framer-mcp-edit',
       changedNodeCount,
       renamedIds,
       propertyErrors: propertyErrorsOf(output, renamedIds),
@@ -857,13 +1097,89 @@ export function createFramerAgentToolRuntime({
   }
 
   function recordPlan(rawPlan) {
-    const nextBehaviors = normalizeBehaviorPlan({ behaviors: rawPlan.behaviors || [] });
+    requirements = mergeRequirements(requirements, normalizeRequirements(rawPlan.requirements));
     plan = {
       summary: String(rawPlan.summary || '').slice(0, 1000),
-      domains: Array.isArray(rawPlan.domains) ? rawPlan.domains.map(String).slice(0, 12) : [],
       verification: Array.isArray(rawPlan.verification) ? rawPlan.verification.map(String).slice(0, 12) : [],
     };
-    behaviorPlan = mergeBehaviorPlans(behaviorPlan, nextBehaviors);
+    const unchanged = Array.isArray(rawPlan.unchanged) ? rawPlan.unchanged.map(String).filter(Boolean).slice(0, 20) : [];
+    unchangedPending = [...new Set([...unchangedPending, ...unchanged])]
+      .filter((id) => !Object.prototype.hasOwnProperty.call(unchangedBefore, id));
+  }
+
+  // Layers the plan says must stay as they are are recorded before the edit
+  // that could change them.
+  // Measures layers in the user's editor through the Dexter panel. Returns a
+  // map of layer id to its measurement, or null when the panel cannot answer.
+  async function measureInEditor(nodeIds) {
+    const ids = [...new Set(nodeIds.filter(Boolean))].slice(0, UNCHANGED_LAYER_LIMIT);
+    if (!editorMeasures || editorMeasureUnavailable || !ids.length) return null;
+    try {
+      const payload = await callPanelTool({
+        callId: crypto.randomUUID(),
+        name: 'framer_measure',
+        arguments: { nodeIds: ids },
+      });
+      const result = payload?.ok === false ? null : payload?.result ?? payload;
+      if (!result || result.ok === false || !result.layers || typeof result.layers !== 'object') {
+        editorMeasureUnavailable = true;
+        return null;
+      }
+      return result.layers;
+    } catch (error) {
+      editorMeasureUnavailable = true;
+      trace?.warn?.('framer_editor_measure_failed', { message: String(error?.message || error).slice(0, 300) });
+      return null;
+    }
+  }
+
+  // A layer's rendered size from a Framer screenshot, which Framer renders
+  // correctly on every page. It gives no position.
+  async function screenshotSize(nodeId) {
+    try {
+      const result = await client.exec(`return await api.tree.screenshot(${JSON.stringify(nodeId)});`);
+      const url = outputOf(result).result;
+      if (typeof url !== 'string' || !/^https:\/\//.test(url)) return null;
+      const response = await fetchImpl(url, { signal: AbortSignal.timeout(IMAGE_FETCH_TIMEOUT_MS) });
+      if (!response.ok) return null;
+      return imageSize(Buffer.from(await response.arrayBuffer()));
+    } catch {
+      return null;
+    }
+  }
+
+  // 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;
+    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));
+    for (const [id, layer] of Object.entries(layers || {})) {
+      if (layer?.measured && layer.rect && snapshot[id]) snapshot[id].rect = { ...layer.rect, source: 'editor' };
+    }
+    return snapshot;
+  }
+
+  async function snapshotUnchanged() {
+    if (!unchangedPending.length) return;
+    const roots = unchangedPending;
+    unchangedPending = [];
+    try {
+      const snapshot = await snapshotLayers(roots);
+      if (snapshot) Object.assign(unchangedBefore, snapshot);
+    } catch (error) {
+      trace?.warn?.('framer_unchanged_snapshot_failed', { message: String(error?.message || error).slice(0, 300) });
+    }
+  }
+
+  // Only checks read after the last change count.
+  function requirementStatus() {
+    return summarizeRequirements(
+      requirements,
+      checkResults.filter((result) => result.at >= lastMutationAt),
+    );
   }
 
   function firstEditNudge() {
@@ -876,9 +1192,8 @@ export function createFramerAgentToolRuntime({
     const missingChecks = [];
     if (mutationCalls > 0 && lastReadAfterMutationAt < lastMutationAt) missingChecks.push('structural');
     if (required.has('visual') && mutationCalls > 0 && lastVisualAt < lastMutationAt) missingChecks.push('visual');
-    if (required.has('interactions') && behaviorPlan) {
-      const summary = summarizeBehaviorVerification(behaviorPlan, behaviorResults);
-      if (summary.status !== 'verified') missingChecks.push('interactions');
+    if (requirements.length && mutationCalls > 0 && requirementStatus().status !== 'verified') {
+      missingChecks.push('requirements');
     }
     return {
       visualRequired: required.has('visual'),
@@ -951,6 +1266,7 @@ export function createFramerAgentToolRuntime({
         if (images.length) lastVisualAt = Date.now();
       } else if (name === 'framer_read') {
         const program = validateProgram(args.program, { write: false, allowPublishing });
+        callExtra.helpers = helpersUsed(program);
         await ensureProject();
         const result = await client.exec(wrapReadProgram(program));
         const applied = applyReceipt(result, []);
@@ -977,7 +1293,9 @@ export function createFramerAgentToolRuntime({
         const program = validateProgram(args.program, { write: true, allowPublishing });
         if (args.plan && typeof args.plan === 'object') recordPlan(args.plan);
         const screenshotNodeIds = Array.isArray(args.screenshotNodeIds) ? args.screenshotNodeIds : [];
+        callExtra.helpers = helpersUsed(program);
         await ensureProject();
+        await snapshotUnchanged();
         const result = await client.exec(wrapProgram(program));
         const applied = applyReceipt(result, screenshotNodeIds);
         const programError = programErrorOf(applied.output, wrappedLineOffset(program));
@@ -1042,31 +1360,62 @@ export function createFramerAgentToolRuntime({
           ...(applied.images.length ? { modelImages: applied.images } : {}),
           ...(due.length ? { evidenceStillDue: due } : {}),
         };
-      } else if (name === 'framer_verify_interactions') {
-        behaviorPlan = mergeBehaviorPlans(behaviorPlan, normalizeBehaviorPlan({ behaviors: args.behaviors || [] }));
-        const checks = normalizeBehaviorEvidence(args.checks, behaviorPlan);
-        const nodeIds = evidenceNodeIds(checks);
+      } else if (name === 'framer_measure') {
+        const nodeIds = (Array.isArray(args.nodeIds) ? args.nodeIds : []).map((id) => String(id).slice(0, 200)).filter(Boolean).slice(0, 100);
+        const layers = await measureInEditor(nodeIds);
+        if (!layers) {
+          throw toolError('FRAMER_MEASURE_UNAVAILABLE', 'The Dexter panel could not measure right now. Judge sizes and spacing from a screenshot.');
+        }
+        readCalls += 1;
+        payload = {
+          layers: Object.fromEntries(nodeIds.map((id) => {
+            const layer = layers[id];
+            if (!layer?.measured) {
+              return [id, { measured: false, note: layer?.reason === 'not_found' ? 'Framer has no layer with this id.' : 'This layer is not on the page open in the user\'s editor, so it cannot be measured. Judge it from a screenshot.' }];
+            }
+            return [id, { x: layer.x, y: layer.y, width: layer.width, height: layer.height, frame: layer.frameId ? { id: layer.frameId, name: layer.frameName || null } : null }];
+          })),
+        };
+      } else if (name === 'framer_verify') {
+        requirements = mergeRequirements(requirements, normalizeRequirements(args.requirements));
+        const checks = normalizeChecks(args.checks, requirements);
         await ensureProject();
         // Serialized nodes are plain data; live node objects can crash
         // Framer's worker when returned.
-        const result = await client.exec(
-          `return await api.tree.serializeNodes(${JSON.stringify(nodeIds)}, { depth: 0 });`,
-        );
+        // Measures come from the user's editor where it can take them, then
+        // from Framer MCP, then, for sizes, from a screenshot.
+        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 output = outputOf(result);
-        const nodes = output.result || output.nodes || output;
-        const list = Array.isArray(nodes) ? nodes : nodes?.nodes;
-        const nodeMap = new Map();
-        if (Array.isArray(list)) {
-          for (const node of list) {
-            if (node?.id) nodeMap.set(node.id, node);
+        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 : {};
+        let mcpIndex = 0;
+        const measured = [];
+        for (const [index, check] of measures.entries()) {
+          let entry = fromEditor[index] || (Array.isArray(fromMcp) ? fromMcp[mcpIndex++] : null);
+          if (entry?.unmeasured && (check.measure === 'width' || check.measure === 'height')) {
+            const size = await screenshotSize(check.nodeId);
+            if (size) entry = { value: size[check.measure] };
           }
-        } else if (nodes && typeof nodes === 'object') {
-          for (const [id, node] of Object.entries(nodes)) nodeMap.set(id, node);
+          measured.push(entry);
+        }
+        const nodeMap = new Map();
+        for (const node of Array.isArray(nodes) ? nodes : []) {
+          if (node?.id) nodeMap.set(node.id, node);
         }
-        behaviorResults = verifyBehaviorChecks({ checks, nodes: nodeMap });
+        const at = Date.now();
+        const results = verifyChecks({ checks, nodes: nodeMap, measurements: Array.isArray(measured) ? measured : [] })
+          .map((item) => ({ ...item, at }));
+        const checkedRequirements = new Set(results.map((item) => item.requirementId));
+        checkResults = [...checkResults.filter((item) => !checkedRequirements.has(item.requirementId)), ...results];
         readCalls += 1;
-        if (mutationCalls > 0) lastReadAfterMutationAt = Date.now();
-        payload = summarizeBehaviorVerification(behaviorPlan, behaviorResults);
+        if (mutationCalls > 0) lastReadAfterMutationAt = at;
+        payload = requirementStatus();
+        if (payload.requirements.some((item) => item.verdict === 'unmeasured')) {
+          payload = { ...payload, unmeasuredNote: 'Unmeasured requirements could not be measured on this page. They are not failures; judge them from a screenshot when they matter, and do not change layers because of them.' };
+        }
       } else {
         throw toolError('FRAMER_AGENT_TOOL_UNKNOWN', `Unknown Framer tool ${name}.`);
       }
@@ -1074,6 +1423,11 @@ export function createFramerAgentToolRuntime({
       noteFramerAnswer(null);
       const nudge = category === 'read' ? firstEditNudge() : null;
       if (nudge) payload = { ...payload, nextStep: nudge };
+      if (Array.isArray(payload?.modelImages)) {
+        const { modelImages, ...rest } = payload;
+        const ready = await modelReadyImages(modelImages);
+        payload = ready.length ? { ...rest, modelImages: ready } : rest;
+      }
       reportActivity({
         kind: 'tool_active',
         source: 'framer-mcp',
@@ -1175,27 +1529,52 @@ export function createFramerAgentToolRuntime({
     return { content: guidance.content, inventory: guidance.inventory };
   }
 
+  function unmetRequirements() {
+    if (!requirements.length || mutationCalls === 0) return [];
+    return requirementStatus().requirements
+      .filter((item) => !item.checked || (item.verdict !== 'verified' && item.verdict !== 'unmeasured'))
+      .map((item) => ({
+        id: item.requirementId,
+        text: item.text,
+        reason: item.contradictions[0]
+          || item.unknowns[0]
+          || (item.uncheckedNodeIds.length ? `not checked on ${item.uncheckedNodeIds.join(', ')}` : 'not checked after the last change'),
+      }));
+  }
+
+  // What Dexter's own reads found after the model said it was done. These are
+  // facts for the model to weigh against the user's request, not orders: it
+  // decides whether to change something or to tell the user plainly.
   function verificationRepairText() {
     if (mutationCalls === 0) return null;
     const missing = verification().missingChecks;
     const propertyErrors = lingeringPropertyErrors();
-    const lines = [];
+    const facts = [];
     if (propertyErrors.length) {
-      lines.push(`Framer did not apply every property: ${propertyErrors.map((error) => `${error.nodeId}.${error.property}: ${error.message}`).join('; ')}. Repair those properties with framer_edit.`);
+      facts.push(`Framer rejected these properties, so they are not set: ${propertyErrors.map((error) => `${error.nodeId}.${error.property}: ${error.message}`).join('; ')}.`);
     }
     if (pendingRepair?.claimed?.length) {
-      lines.push(`These claimed node ids were not touched by an edit: ${pendingRepair.claimed.join(', ')}. Edit those nodes or remove them from changedNodeIds.`);
+      facts.push(`Your changedNodeIds lists layers no edit touched: ${pendingRepair.claimed.join(', ')}.`);
     }
     if (pendingRepair?.failed?.length) {
-      lines.push(`Your latest edit of these claimed node ids failed, so it changed nothing: ${pendingRepair.failed.join(', ')}. Apply that change with framer_edit, or remove them from changedNodeIds and say in the summary what was not changed.`);
+      facts.push(`Your latest edit of these layers failed, so it changed nothing: ${pendingRepair.failed.join(', ')}.`);
+    }
+    if (missing.includes('visual')) {
+      facts.push('Your plan declared visual verification, and there is no screenshot after your last change.');
     }
-    for (const check of missing) {
-      if (check === 'structural') lines.push('perform a focused live read after the latest mutation');
-      else if (check === 'visual') lines.push('capture and inspect a screenshot of the affected canvas after the latest mutation');
-      else if (check === 'interactions') lines.push('confirm declared behaviors with framer_verify_interactions');
+    const unmet = unmetRequirements();
+    if (unmet.length) {
+      facts.push(`Framer shows these requirements from your plan as not met: ${unmet.map((item) => `${item.text} (${item.reason})`).join('; ')}.`);
     }
-    if (!lines.length) return null;
-    return lines.join(' ');
+    if (unchangedChanges.length) {
+      facts.push(`These layers you planned to leave as they were now read differently: ${unchangedChanges.join('; ')}.`);
+    }
+    if (!facts.length) return null;
+    return [
+      'Before you finish, here is what Dexter read from Framer after your last change.',
+      ...facts,
+      'Weigh this against what the user asked. Change what is genuinely wrong, or, if it cannot or should not be changed, keep it and tell the user plainly in your summary. Then return the JSON outcome again.',
+    ].join(' ');
   }
 
   // The read after the last change is a mechanical check, so the harness
@@ -1249,6 +1628,16 @@ export function createFramerAgentToolRuntime({
       }
     }
     pendingRepair = { claimed: missing, failed };
+    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) : [];
+        readCalls += 1;
+      } catch {
+        unchangedChanges = [];
+      }
+    }
     return pendingRepair;
   }
 
@@ -1256,8 +1645,8 @@ export function createFramerAgentToolRuntime({
     if (completion?.projectChanged !== true || mutationCalls > 0) return null;
     return [
       'Your summary says you changed the Framer project, but no layer reads differently after your edits.',
-      'Continue the same task: find every target the user meant, apply the change with framer_edit, verify it, then return the required JSON outcome.',
-      'If you cannot find or change a target, name it in the summary and set projectChanged to false.',
+      'If the user wants that change, apply it with framer_edit and verify it.',
+      'If it cannot be done, or should not be, say so plainly in the summary and set projectChanged to false. Then return the JSON outcome again.',
     ].join(' ');
   }
 
@@ -1267,7 +1656,8 @@ export function createFramerAgentToolRuntime({
     if (lastEdit?.status === 'failed') return null;
     return [
       'You returned failed without changing the Framer project, and no tool refused the work.',
-      'Continue the same task from the current project state: plan it, apply the change, verify it, then return the required JSON outcome.',
+      'If the request can be done, continue it from the current project state.',
+      'If it cannot be done, or the user said to leave it, return completed and explain plainly what is in the way.',
     ].join(' ');
   }
 
@@ -1296,11 +1686,27 @@ export function createFramerAgentToolRuntime({
         output: unbacked.join(', '),
       });
     }
+    const unmet = unmetRequirements();
+    if (unmet.length) {
+      checks.push({
+        command: REQUIREMENTS_CHECK,
+        status: 'failed',
+        output: unmet.map((item) => `${item.id}: ${item.reason}`).join('; ').slice(0, 2000),
+      });
+    }
+    if (unchangedChanges.length) {
+      checks.push({
+        command: UNCHANGED_CHECK,
+        status: 'failed',
+        output: unchangedChanges.join('; ').slice(0, 2000),
+      });
+    }
     // The model's own plan sets the evidence it owes; a run that changed the
     // project and skipped it is not accepted as done.
     const state = verification();
-    if (mutationCalls > 0 && !state.completed) {
-      const missing = state.missingChecks.map((check) => {
+    const missingEvidence = state.missingChecks.filter((check) => check !== 'requirements');
+    if (mutationCalls > 0 && missingEvidence.length) {
+      const missing = missingEvidence.map((check) => {
         if (check === 'structural') return 'a read after the last change';
         if (check === 'visual') return 'a screenshot after the last change';
         return `${check} verification after the last change`;
@@ -1381,7 +1787,9 @@ export function createFramerAgentToolRuntime({
       return { unresolvedTargets: [] };
     },
     loadProjectGuidance,
-    configurePromptContext() {},
+    configurePromptContext(context = {}) {
+      promptContext = { ...context };
+    },
     invoke,
     startGateway,
     synchronize: async () => ({ synchronized: true, sourceHash: null }),
@@ -1404,6 +1812,15 @@ export function createFramerAgentToolRuntime({
       mutationReceipts: mutationReceipts.map((receipt) => ({ ...receipt })),
       branch: branchChange,
       verification: verification(),
+      requirements: requirementStatus().requirements.map((item) => ({
+        id: item.requirementId,
+        verdict: item.verdict,
+        checked: item.checked,
+      })),
+      unchangedLayers: Object.keys(unchangedBefore).length,
+      unchangedChanges: unchangedChanges.length,
+      doctrineLoaded: promptContext.doctrineLoaded === true,
+      doctrineVersion: promptContext.doctrineVersion || null,
       framerGuidanceLoaded: guidance.loaded,
       guidance: {
         loaded: guidance.loaded,