@gakim-digital/dexter-bridge 0.13.8 → 0.13.9

package/package.json

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

package/src/agent.js

@@ -10,6 +10,7 @@ import {
   findWebflowImages,
   getFramerProjectAuthorization,
   webflowMcpEndpoint,
+  getFramerUndoProgram,
   readFramerWebsite,
   isCompanionPairingInvalidError,
   postRunEvent,
@@ -2771,6 +2772,17 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
                   allowInsecureHttp: options.allowInsecureHttp,
                 })
             : undefined,
+        undoProgram:
+          options.apiBaseUrl && options.deviceToken
+            ? ({ runId: targetRunId }) =>
+                getFramerUndoProgram(options.apiBaseUrl, {
+                  deviceToken: options.deviceToken,
+                  runId: run.runId,
+                  targetRunId,
+                  fetchImpl: options.fetchImpl,
+                  allowInsecureHttp: options.allowInsecureHttp,
+                })
+            : undefined,
       })
     : webflowOutcome
       ? createWebflowToolRuntime({

package/src/api.js

@@ -267,6 +267,33 @@ export function readFramerWebsite(apiBaseUrl, {
   );
 }
 
+// The program that puts back what an earlier run in this conversation
+// changed. Dexter writes it from that run's undo record.
+export function getFramerUndoProgram(apiBaseUrl, {
+  deviceToken,
+  runId,
+  targetRunId,
+  fetchImpl,
+  allowInsecureHttp,
+}) {
+  return requestJson(
+    apiBaseUrl,
+    `/ai/framer/companion/runs/${encodeURIComponent(runId)}/undo-program`,
+    {
+      method: 'POST',
+      deviceToken,
+      fetchImpl,
+      allowInsecureHttp,
+      timeoutMs: 30_000,
+      body: {
+        targetRunId,
+        platform: process.platform,
+        companionVersion: BRIDGE_VERSION,
+      },
+    },
+  );
+}
+
 // The run's Webflow MCP endpoint on Dexter's API. The Webflow token never leaves the API.
 export function webflowMcpEndpoint(apiBaseUrl, { deviceToken, runId, allowInsecureHttp }) {
   return {

package/src/framerTools.js

@@ -183,6 +183,18 @@ const TOOL_DEFINITIONS = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'framer_undo_run',
+    description: 'Put back exactly what one earlier run in this conversation changed, from context.recentRuns: settings and text return, layers it added are removed, layers it removed come back, and moved layers return to their place. Anything changed again since that run is left as it is and reported. Use it when the user asks to revert or undo earlier work, instead of rebuilding the earlier state by hand. To go further back, undo the later runs first, newest first.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        runId: { type: 'string', minLength: 1, maxLength: 300, description: 'The runId from context.recentRuns.' },
+      },
+      required: ['runId'],
+      additionalProperties: false,
+    },
+  },
   {
     name: 'framer_read_website',
     description: `Read one page of a website the user named: exact copy per section, fonts and text styles, colours, image URLs (including CSS backgrounds), and desktop and phone screenshots. Use it before recreating or migrating that page. Only sites the user named can be read. ${IMAGE_RESULT_NOTE}`,
@@ -574,9 +586,112 @@ const __dexterTreeGuards = __dexterDeletionAllowed ? {} : {
 const __dexterFileRecorders = Object.fromEntries(['create', 'write', 'applyPatch', 'delete'].map((op) => [op, (args, result) => {
   __dexterFiles.push({ op, path: typeof args[0] === 'string' ? args[0] : '', diagnostics: result && Array.isArray(result.diagnostics) ? result.diagnostics : [] });
 }]));
+// What each change replaced, so Dexter can put it back later. A layer keeps
+// its settings from before its first change; a text layer keeps its
+// paragraphs and runs too. A removed layer keeps everything inside it and its
+// copies on the other breakpoints, which Framer removes with it. Calls whose
+// changes Dexter cannot put back are listed by name.
+const __dexterUndo = { layers: {}, created: [], moved: {}, removed: [], files: {}, unsupported: [] };
+const __dexterCreated = new Set();
+const __dexterTextTypes = new Set(['TextBlock', 'TextRun', 'TextLineBreak', 'TextBulletList', 'TextNumberedList', 'TextListItem', 'TextBlockquote', 'TextTable', 'TextTableRow', 'TextTableCell', 'TextComponentInstance']);
+const __dexterReadNode = (tree, id, json) => {
+  try {
+    const text = json !== undefined ? json : __dexterStateOf(tree, id);
+    return text ? JSON.parse(text) : null;
+  } catch { return null; }
+};
+const __dexterOwn = (node) => {
+  if (!node || node.type === 'RichTextNode') return node;
+  const { children, ...own } = node;
+  return own;
+};
+const __dexterKeep = (tree, id, json) => {
+  if (!id || __dexterCreated.has(id) || __dexterUndo.layers[id]) return;
+  const node = __dexterOwn(__dexterReadNode(tree, id, json));
+  if (node) __dexterUndo.layers[id] = { before: node };
+};
+const __dexterPlace = (tree, id) => {
+  const node = tree.get(id);
+  const parent = node && node.$parentId;
+  if (!parent) return null;
+  const siblings = (tree.get(parent) || {}).children || [];
+  return { parent, index: Math.max(0, siblings.findIndex((child) => child && child.id === id)) };
+};
+const __dexterReplicas = (tree, node) => {
+  const copies = {};
+  if (!node || node.$replicaId || !node.$groundNodeId || !node.$scopeId) return copies;
+  const scope = tree.get(node.$scopeId);
+  for (const variant of (scope && (scope.$breakpoints || scope.$variants)) || []) {
+    const variantId = variant && variant.id;
+    if (!variantId || variantId === node.$groundNodeId) continue;
+    const copy = __dexterReadNode(tree, variantId + node.id);
+    if (copy) copies[variantId] = copy;
+  }
+  return copies;
+};
+const __dexterKeepLayer = (tree, args, json) => __dexterKeep(tree, __dexterLayerOf(args[0]), json);
+const __dexterNoteCreated = (args, result) => {
+  const id = __dexterIdOf(result);
+  if (!id || id.startsWith('v:') || __dexterCreated.has(id)) return;
+  __dexterCreated.add(id);
+  __dexterUndo.created.push(id);
+};
+// An edit to something Dexter could not read first, such as rich text inside
+// a CMS field, cannot be put back; it is listed instead.
+const __dexterUnreadable = (call, args) => {
+  const id = __dexterLayerOf(args[0]);
+  if (!id || __dexterUndo.layers[id] || __dexterCreated.has(id) || __dexterUndo.unsupported.length >= 20) return;
+  __dexterUndo.unsupported.push({ call, target: __dexterIdOf(args[0]) || '' });
+};
+const __dexterTreeUndo = {
+  before: {
+    patch: __dexterKeepLayer,
+    replaceText: __dexterKeepLayer,
+    autofit: __dexterKeepLayer,
+    resetOverrides: __dexterKeepLayer,
+    // Text blocks and runs are inserted into an existing text layer.
+    insert: (tree, args) => {
+      if (__dexterTextTypes.has(args[0])) __dexterKeep(tree, __dexterLayerOf(args[2] && args[2].parent));
+    },
+    move: (tree, args) => {
+      const id = __dexterIdOf(args[0]);
+      if (!id || __dexterCreated.has(id) || __dexterUndo.moved[id]) return;
+      const place = __dexterPlace(tree, id);
+      if (place) __dexterUndo.moved[id] = { before: place, name: (tree.get(id) || {}).name || null };
+    },
+    // Removing a layer on another breakpoint only hides it there.
+    remove: (tree, args, json) => {
+      const id = __dexterIdOf(args[0]);
+      if (!id || __dexterCreated.has(id)) return undefined;
+      const node = __dexterReadNode(tree, id, json);
+      if (!node) return undefined;
+      if (node.$replicaId) { __dexterKeep(tree, id, json); return undefined; }
+      return { id, node, place: __dexterPlace(tree, id), replicas: __dexterReplicas(tree, node) };
+    },
+  },
+  after: {
+    patch: (args) => __dexterUnreadable('patch', args),
+    replaceText: (args) => __dexterUnreadable('replaceText', args),
+    insert: (args, result) => { if (!__dexterTextTypes.has(args[0])) __dexterNoteCreated(args, result); },
+    duplicate: __dexterNoteCreated,
+    createVariant: __dexterNoteCreated,
+    remove: (args, result, removal) => { if (removal) __dexterUndo.removed.push(removal); },
+  },
+  unsupported: new Set(['var', 'changeHomePage', 'createComponentFromFrame', 'flattenComponentInstance', 'makeExternalComponentLocal', 'createABTestVariant', 'setABTestDistribution', 'patchFormDestinations', 'updateTitle']),
+};
+const __dexterFileUndo = {
+  before: Object.fromEntries(['create', 'write', 'applyPatch', 'delete'].map((op) => [op, async (files, args) => {
+    const path = typeof args[0] === 'string' ? args[0] : '';
+    if (!path || Object.prototype.hasOwnProperty.call(__dexterUndo.files, path)) return;
+    let source = null;
+    try { const file = await files.read(path); source = file && typeof file.source === 'string' ? file.source : null; } catch {}
+    __dexterUndo.files[path] = { before: source };
+  }])),
+  after: {},
+};
 // The proxy sits on an empty stand-in that forwards to the real object, so
 // methods can be wrapped even when Framer freezes its API objects.
-const __dexterRecording = (object, recorders, children = {}, compared = new Set(), targets = {}, guards = {}) => new Proxy({}, {
+const __dexterRecording = (object, recorders, children = {}, compared = new Set(), targets = {}, guards = {}, undo = { before: {}, after: {} }) => new Proxy({}, {
   has: (_, key) => Reflect.has(object, key),
   ownKeys: () => Reflect.ownKeys(object),
   getOwnPropertyDescriptor: (_, key) => {
@@ -589,7 +704,10 @@ const __dexterRecording = (object, recorders, children = {}, compared = new Set(
     if (typeof value !== 'function') return value;
     const recorder = recorders[key];
     const checked = compared.has(key);
-    if (!recorder && !checked) return (...args) => value.apply(object, args);
+    const undoBefore = undo.before[key];
+    const undoAfter = undo.after[key];
+    const unsupported = Boolean(undo.unsupported && undo.unsupported.has(key));
+    if (!recorder && !checked && !undoBefore && !undoAfter && !unsupported) return (...args) => value.apply(object, args);
     return (...args) => {
       const fail = (error) => {
         if (__dexterFailed.length < 50) {
@@ -599,27 +717,64 @@ const __dexterRecording = (object, recorders, children = {}, compared = new Set(
       };
       if (guards[key]) guards[key](object, args);
       const layer = checked ? __dexterLayerOf(args[0]) : null;
-      const before = checked ? __dexterStateOf(object, layer) : null;
-      const settle = (result) => {
-        if (!checked) { recorder(args, result); return result; }
-        const after = __dexterStateOf(object, layer);
-        // Without a readable layer, the call's own answer is all there is.
-        const changed = before !== null || after !== null ? before !== after : result !== false;
-        if (changed) __dexterNote(layer);
-        else if (__dexterUnchanged.length < 50) __dexterUnchanged.push({ call: String(key), target: __dexterIdOf(args[0]) || '' });
-        return result;
+      const run = (before, memo) => {
+        const settle = (result) => {
+          if (undoAfter) undoAfter(args, result, memo);
+          if (unsupported && __dexterUndo.unsupported.length < 20) __dexterUndo.unsupported.push({ call: String(key), target: __dexterIdOf(args[0]) || '' });
+          if (!checked) { if (recorder) recorder(args, result); return result; }
+          const after = __dexterStateOf(object, layer);
+          // Without a readable layer, the call's own answer is all there is.
+          const changed = before !== null || after !== null ? before !== after : result !== false;
+          if (changed) __dexterNote(layer);
+          else if (__dexterUnchanged.length < 50) __dexterUnchanged.push({ call: String(key), target: __dexterIdOf(args[0]) || '' });
+          return result;
+        };
+        let result;
+        try { result = value.apply(object, args); } catch (error) { fail(error); }
+        if (result && typeof result.then === 'function') return result.then(settle, fail);
+        return settle(result);
       };
-      let result;
-      try { result = value.apply(object, args); } catch (error) { fail(error); }
-      if (result && typeof result.then === 'function') return result.then(settle, fail);
-      return settle(result);
+      const before = checked ? __dexterStateOf(object, layer) : null;
+      const memo = undoBefore ? undoBefore(object, args, layer === __dexterIdOf(args[0]) && before !== null ? before : undefined) : undefined;
+      // Code files are read before they change, which takes a moment.
+      if (memo && typeof memo.then === 'function') return memo.then(() => run(checked ? __dexterStateOf(object, layer) : null));
+      return run(before, memo);
     };
   },
 });
 const __dexterApi = __dexterRecording(api, {}, {
-  tree: (tree) => __dexterRecording(tree, __dexterTreeRecorders, {}, __dexterCompared, __dexterTreeTarget, __dexterTreeGuards),
-  files: (files) => __dexterRecording(files, __dexterFileRecorders),
+  tree: (tree) => __dexterRecording(tree, __dexterTreeRecorders, {}, __dexterCompared, __dexterTreeTarget, __dexterTreeGuards, __dexterTreeUndo),
+  files: (files) => __dexterRecording(files, __dexterFileRecorders, {}, new Set(), {}, {}, __dexterFileUndo),
 });
+// Read once the program ends: how everything it changed reads now, so a later
+// undo can tell whether someone changed it again since.
+const __dexterUndoRecord = async () => {
+  const tree = api.tree;
+  const layers = {};
+  for (const [id, entry] of Object.entries(__dexterUndo.layers)) {
+    layers[id] = { before: entry.before, after: __dexterOwn(__dexterReadNode(tree, id)) };
+  }
+  const created = [];
+  for (const id of __dexterUndo.created) {
+    const node = __dexterReadNode(tree, id);
+    if (!node) continue;
+    const ids = [];
+    const visit = (inner) => { if (inner && inner.id) ids.push(inner.id); for (const child of (inner && inner.children) || []) visit(child); };
+    visit(node);
+    created.push({ id, after: __dexterOwn(node), ids });
+  }
+  const moved = {};
+  for (const [id, entry] of Object.entries(__dexterUndo.moved)) {
+    moved[id] = { before: entry.before, name: entry.name, after: __dexterPlace(tree, id) };
+  }
+  const files = {};
+  for (const [path, entry] of Object.entries(__dexterUndo.files)) {
+    let source = null;
+    try { const file = await api.files.read(path); source = file && typeof file.source === 'string' ? file.source : null; } catch {}
+    files[path] = { before: entry.before, after: source };
+  }
+  return { layers, created, moved, removed: __dexterUndo.removed, files, unsupported: __dexterUndo.unsupported };
+};
 `;
 
 // Framer MCP lays out only some pages. On the others getRect returns
@@ -758,7 +913,9 @@ try {
 } catch (error) {
   __dexterError = { name: String((error && error.name) || 'Error'), message: String((error && error.message) || error) };
 }
-return { result: __dexterResult, dexterError: __dexterError, dexterFiles: __dexterFiles, dexterTouched: __dexterTouched, dexterFailed: __dexterFailed, dexterUnchanged: __dexterUnchanged, dexterRefused: __dexterRefused };
+let __dexterUndoRecorded = null;
+try { __dexterUndoRecorded = await __dexterUndoRecord(); } catch {}
+return { result: __dexterResult, dexterError: __dexterError, dexterFiles: __dexterFiles, dexterTouched: __dexterTouched, dexterFailed: __dexterFailed, dexterUnchanged: __dexterUnchanged, dexterRefused: __dexterRefused, dexterUndo: __dexterUndoRecorded };
 `;
   return { prefix, body, suffix };
 }
@@ -768,6 +925,71 @@ export function wrapProgram(program, options) {
   return `${prefix}${body}${suffix}`;
 }
 
+// Past this size a run's undo record is not kept; Dexter says the run cannot
+// be undone instead.
+const UNDO_RECORD_LIMIT_BYTES = 8_000_000;
+
+export function emptyUndoRecord() {
+  return { layers: {}, created: [], moved: {}, removed: [], files: {}, unsupported: [] };
+}
+
+// Adds one edit program's undo record to the run's. A layer keeps its
+// settings from before the run and its latest reading. Layers the run added
+// and later removed leave nothing to undo.
+export function mergeUndoRecord(run, program) {
+  if (!program || typeof program !== 'object') return run;
+  const created = new Map(run.created.map((entry) => [entry.id, entry]));
+  for (const entry of Array.isArray(program.created) ? program.created : []) {
+    if (!entry?.id || created.has(entry.id)) continue;
+    run.created.push(entry);
+    created.set(entry.id, entry);
+  }
+  const madeByRun = new Set(run.created.flatMap((entry) => entry.ids || [entry.id]));
+  for (const [id, entry] of Object.entries(program.layers || {})) {
+    if (madeByRun.has(id)) {
+      if (created.has(id)) created.get(id).after = entry.after;
+    } else if (run.layers[id]) {
+      run.layers[id].after = entry.after;
+    } else {
+      run.layers[id] = entry;
+    }
+  }
+  for (const [id, entry] of Object.entries(program.moved || {})) {
+    if (madeByRun.has(id)) continue;
+    if (run.moved[id]) run.moved[id].after = entry.after;
+    else run.moved[id] = entry;
+  }
+  for (const entry of Array.isArray(program.removed) ? program.removed : []) {
+    if (!entry?.id) continue;
+    if (madeByRun.has(entry.id)) {
+      run.created = run.created.filter((made) => made.id !== entry.id);
+      continue;
+    }
+    run.removed.push(entry);
+  }
+  for (const [path, entry] of Object.entries(program.files || {})) {
+    if (run.files[path]) run.files[path].after = entry.after;
+    else run.files[path] = entry;
+  }
+  for (const call of Array.isArray(program.unsupported) ? program.unsupported : []) {
+    if (run.unsupported.length >= 20) break;
+    if (!run.unsupported.some((known) => known.call === call.call && known.target === call.target)) {
+      run.unsupported.push({ call: String(call.call || ''), target: String(call.target || '') });
+    }
+  }
+  return run;
+}
+
+export function undoRecordForSummary(record) {
+  const empty = !Object.keys(record.layers).length && !record.created.length && !Object.keys(record.moved).length
+    && !record.removed.length && !Object.keys(record.files).length && !record.unsupported.length;
+  if (empty) return null;
+  if (JSON.stringify(record).length > UNDO_RECORD_LIMIT_BYTES) {
+    return { tooLarge: true, unsupported: record.unsupported };
+  }
+  return record;
+}
+
 // Lines the wrapper adds before the model's program; Framer's compile errors
 // count from the top of the wrapped program.
 export function wrappedLineOffset(program) {
@@ -954,6 +1176,7 @@ export function createFramerAgentToolRuntime({
   authorizeProject,
   readWebsite,
   callPanelTool,
+  undoProgram,
   mcpClient,
   getAccessToken,
   trace,
@@ -1004,6 +1227,8 @@ export function createFramerAgentToolRuntime({
   let firstToolAt = null;
   let guidance = { content: '', inventory: '', loaded: false, files: [] };
   const mutationReceipts = [];
+  const undoRecord = emptyUndoRecord();
+  const undoneRuns = [];
   // Layer id → result of the latest edit call on it ('changed' or 'failed').
   const editOutcomes = new Map();
   const toolCalls = [];
@@ -1156,6 +1381,7 @@ export function createFramerAgentToolRuntime({
         ...(call.message ? { message: String(call.message).slice(0, 300) } : {}),
       }));
     const failedCalls = calls(inner.dexterFailed);
+    mergeUndoRecord(undoRecord, inner.dexterUndo);
     const receipt = {
       kind: 'framer-mcp-edit',
       changedNodeCount,
@@ -1452,7 +1678,6 @@ export function createFramerAgentToolRuntime({
             : {}),
           ...(screenshotWarning ? { screenshotWarning } : {}),
           ...(programResult !== undefined ? { result: programResult } : {}),
-          changedNodeCount: applied.receipt.changedNodeCount,
           // Framer gives inserted nodes new ids; later programs must use them.
           renamedIds: applied.receipt.renamedIds,
           touchedNodeIds: applied.receipt.touchedNodeIds,
@@ -1497,6 +1722,39 @@ export function createFramerAgentToolRuntime({
             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_undo_run') {
+        category = 'mutation';
+        if (typeof undoProgram !== 'function') {
+          throw toolError('FRAMER_UNDO_UNAVAILABLE', 'Undo is not available for this run.');
+        }
+        const runId = String(args.runId || '').trim();
+        callExtra.undoRunId = runId;
+        // Dexter writes the undo program from what that run recorded. It runs
+        // like an edit, so this run records it too and can itself be undone.
+        const prepared = await undoProgram({ runId });
+        if (!prepared?.program) {
+          throw toolError(prepared?.code || 'FRAMER_UNDO_UNAVAILABLE', prepared?.error || 'That run cannot be undone.');
+        }
+        await ensureProject();
+        const result = await client.exec(wrapProgram(prepared.program, { allowContentDeletion: true }));
+        const applied = applyReceipt(result, []);
+        const programError = programErrorOf(applied.output, wrappedLineOffset(prepared.program));
+        if (programError) {
+          throw toolError(
+            'FRAMER_UNDO_FAILED',
+            `${programError.message}${applied.changed ? ' Part of the undo was applied; read the project before going on.' : ''}`,
+          );
+        }
+        const report = applied.output.result && typeof applied.output.result === 'object'
+          ? applied.output.result.result
+          : null;
+        undoneRuns.push({ runId, report: boundedResult(report) });
+        payload = {
+          undone: runId,
+          report: boundedResult(report),
+          touchedNodeIds: applied.receipt.touchedNodeIds,
+          note: 'skipped lists what was changed again after that run and was left as it is; failed lists what could not be put back. Tell the user about both.',
+        };
       } else if (name === 'framer_verify') {
         requirements = mergeRequirements(requirements, normalizeRequirements(args.requirements));
         const checks = normalizeChecks(args.checks, requirements);
@@ -1991,6 +2249,8 @@ export function createFramerAgentToolRuntime({
       toolCallCount,
       toolCalls: toolCalls.map((call) => ({ ...call })),
       mutationReceipts: mutationReceipts.map((receipt) => ({ ...receipt })),
+      undo: undoRecordForSummary(undoRecord),
+      undoneRuns: undoneRuns.map((entry) => ({ ...entry })),
       branch: branchChange,
       verification: verification(),
       requirements: requirementStatus().requirements.map((item) => ({

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.