@gakim-digital/dexter-bridge 0.12.1 → 0.12.2

package/package.json

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

package/src/agent.js

@@ -3000,7 +3000,7 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
       });
       const repairResult = await Promise.race([
         executeProviderOutcome(
-          repairPrompt,
+          `${repairPrompt} The designer never sees this note: your summary still answers their original request and does not mention it.`,
           providerSessionId
             || rememberedSession?.providerSessionId
             || sessionKey,

package/src/framerMcpClient.js

@@ -123,14 +123,14 @@ export function createFramerMcpClient({
     sdkClient = client;
   }
 
-  async function rawCall(name, args) {
-    if (typeof callTool === 'function') return callTool(name, args);
+  async function rawCall(name, args, callTimeoutMs = timeoutMs) {
+    if (typeof callTool === 'function') return callTool(name, args, { timeoutMs: callTimeoutMs });
     await connect();
     try {
       return await sdkClient.callTool(
         { name, arguments: args },
         undefined,
-        { timeout: timeoutMs, resetTimeoutOnProgress: true },
+        { timeout: callTimeoutMs, resetTimeoutOnProgress: true },
       );
     } catch (error) {
       if (isUnauthorized(error)) {
@@ -146,16 +146,16 @@ export function createFramerMcpClient({
 
   // An expired session is refused before the program runs, so reopening the
   // project and retrying once cannot apply a change twice.
-  async function call(name, args, retried = false) {
+  async function call(name, args, { retried = false, timeoutMs: callTimeoutMs } = {}) {
     let result;
     try {
-      result = unwrap(await rawCall(name, args));
+      result = unwrap(await rawCall(name, args, callTimeoutMs));
     } catch (error) {
       const expired = error?.code === 'FRAMER_MCP_SESSION_EXPIRED'
         || SESSION_EXPIRED_PATTERN.test(String(error?.message || ''));
       if (!expired || retried || !projectId || name === 'open_project') throw error;
       await openProject(projectId);
-      return call(name, { ...args, session }, true);
+      return call(name, { ...args, session }, { retried: true, timeoutMs: callTimeoutMs });
     }
     return result;
   }
@@ -181,9 +181,9 @@ export function createFramerMcpClient({
     readme: () => readme,
     session: () => session,
     projectId: () => projectId,
-    async exec(program) {
+    async exec(program, { timeoutMs: callTimeoutMs } = {}) {
       requireSession();
-      return call('exec', { session, program });
+      return call('exec', { session, program }, { timeoutMs: callTimeoutMs });
     },
     async readDocs(paths) {
       requireSession();

package/src/framerTools.js

@@ -43,9 +43,13 @@ 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 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 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.';
+
 // Item shapes the behavior contract (framerBehaviorContract.js) accepts.
 const BEHAVIOR_SCHEMA = {
   type: 'object',
@@ -72,7 +76,7 @@ const BEHAVIOR_CHECK_SCHEMA = {
 const TOOL_DEFINITIONS = [
   {
     name: 'framer_read',
-    description: 'Read the open Framer project by running a program. Use api.tree.getNode, getNodes, serialize, and serializeNodes. Stock image search is api.images.search({ query }), one call per query. Fonts are api.fonts.get and api.fonts.list({ query }). There is no framer global. This tool cannot change the project.',
+    description: `Read the open Framer project by running a program. Use api.tree.getNode, getNodes, serialize, and serializeNodes. Stock image search is api.images.search({ query }), one call per query. Fonts are api.fonts.get and api.fonts.list({ query }). There is no framer global. ${MEASURE_TOOL_NOTE} This tool cannot change the project.`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -84,7 +88,7 @@ const TOOL_DEFINITIONS = [
   },
   {
     name: 'framer_edit',
-    description: 'Change the open Framer project by running a program. Use api.tree.insert, patch, remove, move, and replaceText. Place an SVG with tree.insert("SVGNode", id, { svg, intrinsicWidth, intrinsicHeight }). Write code files with api.files.create, write, or applyPatch. Search stock images with api.images.search({ query }). Place an image by setting fill to await api.tree.assetReference(url) with a public image URL. Load fonts with api.fonts. Pass screenshotNodeIds for the nodes you want to see after the edit. Include plan on your first framer_edit.',
+    description: `Change the open Framer project by running a program. Use api.tree.insert, patch, remove, move, and replaceText. Place an SVG with tree.insert("SVGNode", id, { svg, intrinsicWidth, intrinsicHeight }). Write code files with api.files.create, write, or applyPatch. Search stock images with api.images.search({ query }). Place an image by setting fill to await api.tree.assetReference(url) with a public image URL. Load fonts with api.fonts. Pass screenshotNodeIds for the nodes you want to see after the edit. Include plan on your first framer_edit. ${MEASURE_TOOL_NOTE}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -178,6 +182,24 @@ function isFramerTimeout(error) {
   return error?.code === -32001 || FRAMER_TIMEOUT_PATTERN.test(String(error?.message || ''));
 }
 
+// A healthy Framer answers a no-op program in about a second, and setup calls
+// finish within 15 seconds; when Framer stalls, every call waits out its
+// 60-second limit. A run starts only after Framer answers within this time.
+const FRAMER_PROBE_TIMEOUT_MS = 20_000;
+
+function framerNotRespondingError(changesKept) {
+  return Object.assign(
+    toolError(
+      'FRAMER_NOT_RESPONDING',
+      changesKept
+        ? 'Framer stopped running edits on this project partway through, so Dexter stopped. The changes made before that were kept. This is on Framer’s side and can last several minutes, so wait a little before sending again.'
+        : 'Framer isn’t running edits on this project right now, so Dexter stopped before changing anything. This is on Framer’s side and can last several minutes, so wait a little before sending again.',
+      503,
+    ),
+    { retryable: true },
+  );
+}
+
 function codeOutsideLiterals(code) {
   let visible = '';
   for (const token of jsTokens(String(code || ''))) {
@@ -366,7 +388,11 @@ const __dexterStateOf = (tree, id) => {
 };
 const __dexterCompared = new Set(['patch', 'replaceText', 'remove']);
 const __dexterTreeRecorders = {
-  insert: (args, result) => __dexterNote(args[1], result),
+  insert: (args, result) => {
+    __dexterNote(args[1], result);
+    const real = __dexterIdOf(result);
+    if (typeof args[1] === 'string' && real) __dexterInsertedIds[args[1]] = real;
+  },
   move: (args) => __dexterNote(args[0]),
   duplicate: (args, result) => __dexterNote(args[0], args[1], result),
   patchFormDestinations: (args) => __dexterNote(args[0]),
@@ -424,15 +450,92 @@ const __dexterApi = __dexterRecording(api, {}, {
 });
 `;
 
-function wrapperParts(program) {
+// 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 = `
+// 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 = {};
+const dexter = (() => {
+  const tree = api.tree;
+  const idOf = (value) => {
+    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 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 };
+    const frame = await tree.getGroundNodeFor(id);
+    let x = rect.x;
+    let y = rect.y;
+    if (!frame || frame.id !== id) {
+      for (const ancestor of (await tree.getAncestorsFor(id)) || []) {
+        if (frame && ancestor.id === frame.id) break;
+        const box = await tree.getRect(ancestor.id);
+        if (box) { x += box.x; y += box.y; }
+      }
+    }
+    const measured = { id, name: node.name || null, frame: frame ? { id: frame.id, name: frame.name || null } : null, x, y, width: rect.width, height: rect.height };
+    if (node.type === 'RichTextNode' && /px$/.test(String(node.height || ''))) {
+      measured.note = 'This text box has a fixed height of ' + node.height + '; its words may not fill it, so visible space around them can be larger than the box edges show.';
+    }
+    return measured;
+  };
+  const measureAll = async (values) => { const out = []; for (const value of values) out.push(await one(value)); return out; };
+  return {
+    async measure(values) {
+      await settle();
+      return measureAll(Array.isArray(values) ? values : [values]);
+    },
+    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.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));
+      return { a, b, vertical, horizontal, overlap: vertical < 0 && horizontal < 0 };
+    },
+  };
+})();
+`;
+
+function splitStep(program) {
   const source = String(program || '');
   // Framer shows a leading "// @step" comment as progress, so it stays first.
   // The line it leaves behind keeps the program's own line numbers intact.
   const step = source.match(/^\s*(\/\/\s*@step[^\n]*)/)?.[1] || '';
-  const body = step ? source.replace(step, '') : source;
+  return { step, body: step ? source.replace(step, '') : source };
+}
+
+// A read stays at the top level so Framer's error lines point into it.
+function readParts(program) {
+  const { step, body } = splitStep(program);
+  return { prefix: `${step}\n${MEASURE_PRELUDE}\n`, body };
+}
+
+export function wrapReadProgram(program) {
+  const { prefix, body } = readParts(program);
+  return `${prefix}${body}`;
+}
+
+export function wrappedReadLineOffset(program) {
+  return readParts(program).prefix.split('\n').length - 1;
+}
+
+function wrapperParts(program) {
+  const { step, body } = splitStep(program);
   // A program that throws still keeps the changes it made before the throw,
   // so the error is caught here and returned with the record of those changes.
   const prefix = `${step}
+${MEASURE_PRELUDE}
 ${RECORDING_PRELUDE}
 let __dexterResult;
 let __dexterError = null;
@@ -485,14 +588,30 @@ for (const id of ${JSON.stringify(ids)}) {
 return taken`;
 }
 
-function claimedTargetProgram(claimed, touched) {
+// Checks layers the model claimed against the layers the run changed. A
+// claimed layer counts when an edit changed it, a layer inside it, or a layer
+// around it. A claimed page also counts when the run changed something shared
+// by every page: a layer outside all pages (the site-wide layout or a
+// component) or a code file.
+export function claimedTargetProgram(claimed, touched, sharedChange = false) {
   return `
 const { tree } = api;
 const touched = new Set(${JSON.stringify(touched.slice(0, 500))});
+const isPage = (node) => Boolean(node) && node.type === 'WebPageNode';
+let shared = ${sharedChange ? 'true' : 'false'};
+if (!shared) {
+  for (const id of touched) {
+    const node = tree.get(id);
+    if (!node || isPage(node)) continue;
+    const ancestors = (await tree.getAncestorsFor(id)) || [];
+    if (!ancestors.some(isPage)) { shared = true; break; }
+  }
+}
 const verdicts = {};
 for (const id of ${JSON.stringify(claimed.slice(0, 200))}) {
   const node = tree.get(id);
   if (!node) { verdicts[id] = 'missing'; continue; }
+  if (shared && isPage(node)) { verdicts[id] = 'related'; continue; }
   const ancestors = (await tree.getAncestorsFor(id)) || [];
   if (ancestors.some((ancestor) => touched.has(ancestor.id))) { verdicts[id] = 'related'; continue; }
   let related = false;
@@ -637,17 +756,28 @@ export function createFramerAgentToolRuntime({
     consecutiveTimeouts += 1;
     if (consecutiveTimeouts < 2) return;
     if (!fatalError) {
-      fatalError = Object.assign(
-        toolError(
-          'FRAMER_NOT_RESPONDING',
-          mutationCalls > 0
-            ? 'Framer stopped responding, so Dexter stopped. The changes made before that were kept; try again in a minute.'
-            : 'Framer isn’t responding right now, so Dexter stopped. Nothing was changed; try again in a minute.',
-          503,
-        ),
-        { retryable: true },
-      );
+      fatalError = framerNotRespondingError(mutationCalls > 0);
+      signalFatal(fatalError);
+    }
+  }
+
+  // Ends the run before any setup when Framer does not answer a no-op
+  // program, instead of letting setup and the first read each wait a minute.
+  async function probeFramer() {
+    const startedAt = Date.now();
+    try {
+      await client.exec('return true;', { timeoutMs: FRAMER_PROBE_TIMEOUT_MS });
+      trace?.info?.('framer_probe', { durationMs: Date.now() - startedAt });
+    } catch (error) {
+      trace?.warn?.('framer_probe_failed', {
+        durationMs: Date.now() - startedAt,
+        code: error?.code,
+        message: String(error?.message || error).slice(0, 300),
+      });
+      if (!isFramerTimeout(error)) return;
+      fatalError = framerNotRespondingError(false);
       signalFatal(fatalError);
+      throw fatalError;
     }
   }
 
@@ -822,7 +952,7 @@ export function createFramerAgentToolRuntime({
       } else if (name === 'framer_read') {
         const program = validateProgram(args.program, { write: false, allowPublishing });
         await ensureProject();
-        const result = await client.exec(program);
+        const result = await client.exec(wrapReadProgram(program));
         const applied = applyReceipt(result, []);
         if (applied.changed) {
           throw toolError(
@@ -830,7 +960,7 @@ export function createFramerAgentToolRuntime({
             'A read changed the Framer project. Use framer_edit for changes.',
           );
         }
-        const readError = programErrorOf(applied.output);
+        const readError = programErrorOf(applied.output, wrappedReadLineOffset(program));
         if (readError) {
           throw toolError('FRAMER_PROGRAM_FAILED', `${readError.message} (${readError.type})`);
         }
@@ -1105,7 +1235,8 @@ export function createFramerAgentToolRuntime({
       // around it, such as a card whose title was rewritten.
       try {
         await ensureProject();
-        const result = await client.exec(claimedTargetProgram(missing, [...known]));
+        const codeFilesChanged = mutationReceipts.some((receipt) => (receipt.codeFiles || []).length > 0);
+        const result = await client.exec(claimedTargetProgram(missing, [...known], codeFilesChanged));
         const verdicts = outputOf(result).result;
         if (verdicts && typeof verdicts === 'object') {
           missing = missing.filter((id) => verdicts[id] !== 'related');
@@ -1246,6 +1377,7 @@ export function createFramerAgentToolRuntime({
     toolNames: definitions.map((definition) => definition.name),
     preflight: async () => {
       await ensureProject();
+      await probeFramer();
       return { unresolvedTargets: [] };
     },
     loadProjectGuidance,

package/src/protocol.js

@@ -404,6 +404,11 @@ export function normalizeModelTurnCompletion(raw, fallbackModel = 'local-compani
   };
 }
 
+// Dexter sometimes sends the model back to fix or verify something before it
+// finishes. Its final summary still answers the designer's request, not that
+// note, which the designer never sees.
+const REPAIR_SUMMARY_RULE = 'Write the summary for the designer about the task they asked for: what is now different on their site, in their words. If Dexter sends you back to fix or verify something, that note is invisible to the designer, so never answer it in the summary or mention repairs, property errors, layer ids, replicas, or checks.';
+
 export function runSummary(run) {
   return {
     runId: run?.runId,
@@ -494,6 +499,7 @@ export function buildFramerOutcomePrompt(outcome = {}, product, promptContext =
     'You decide which evidence the task needs. Declare visual verification in your task plan when the result must be judged by eye, such as layout or styling work or a build from a reference image, and then inspect a screenshot after your final mutation. When building from a reference attachment or a website read with framer_read_website, compare that final screenshot against the reference images. Claim a visual comparison with a reference only when you saw that reference as an image in this run; if you worked from text descriptions alone, say so in the check. A screenshot before editing is optional; take one when you need to preserve or compare the current look. Use verifies on final reads to establish link, responsive, code, or data checks when your plan requires them.',
     'Confirm declared behaviors with framer_verify_interactions after your final change: for each target node, name the Framer property that carries the behavior and, when it matters, a literal its value must contain, such as a route or SHOW_OVERLAY. This is structural evidence that the property is set, not runtime playback; describe it that way. If a property is not exposed, report the behavior as unverified instead of changing working parts.',
     'For visual work, evaluate hierarchy, spacing, contrast, typography, balance, imagery, interaction states, and responsive integrity.',
+    'When the user asks for an exact distance or size, such as a gap in pixels or equal spacing between sections, measure the layers involved with dexter.measure and dexter.gap before changing anything, to find what creates the space now: a stack gap, padding, a fixed height, or a box larger than its content. Change that cause instead of adding spacing on top of it, then measure again, including the neighbouring layers, so nothing overlaps. State a pixel value in your summary only when you measured it; otherwise describe the change without numbers.',
     'If one visual detail, such as a gradient, an effect, or the stacking of layers, still does not look right after two attempts, keep the closest version, finish the rest of the task, and name the difference in your summary. Do not run diagnostic experiments on the user\'s canvas, such as test colours or throwaway layers.',
     'For depth and 3D, set native transforms with api.tree inside framer_edit, as described in the Framer guidance Transforms section: perspective on the parent, preserve3d on a container whose children must stay in 3D space, rotateX, rotateY, rotateZ, translateZ, and transformOrigin on the moving layers, and backfaceVisibility for flip faces. Rotations without a parent perspective render flat. Spend 3D on one signature moment, such as a tilted product mockup, layered card stack, flip card, or hover tilt; keep text readable, reduce or flatten the effect on smaller breakpoints, and confirm it in a screenshot. Do not fake 3D with images or code components when native transforms can achieve it.',
     'You decide when the run is complete. Avoid repeated inspection of unchanged evidence and stop when the requested outcome has been implemented and verified.',
@@ -501,6 +507,7 @@ export function buildFramerOutcomePrompt(outcome = {}, product, promptContext =
     'If Framer authorization or a required user decision is missing, return blocked with a concise explanation. Otherwise return completed only after you have finished and verified the work.',
     'A greeting, thanks, or question that needs no project change is not blocked: answer it in summary without reading or editing the project and return completed.',
     'Set projectChanged to true only when this run applied a change to the Framer project, and list the ids of the layers you changed in changedNodeIds. The summary must describe only changes that were applied; if you could not find or change something, say so plainly instead.',
+    REPAIR_SUMMARY_RULE,
     'When finished, return exactly one JSON object and no markdown.',
     '{"status":"completed|blocked|failed","summary":"one or two short, non-technical sentences for the designer","checks":[{"command":"what you verified","status":"passed|failed|skipped","output":"short result"}],"blockedReason":null,"projectChanged":false,"changedNodeIds":[]}',
     doctrine

package/LICENSE

@@ -1,16 +0,0 @@
-Dexter Bridge License
-
-Copyright (c) 2026 InstaWeb AI. All rights reserved.
-
-Permission is granted to download, install, and run this software solely to
-connect your local machine to the Dexter / InstaWeb AI service. You may not
-modify, redistribute, sublicense, or sell this software or use it to build a
-competing service.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.