@gakim-digital/dexter-bridge 0.11.2 → 0.11.3

package/README.md

@@ -52,7 +52,10 @@ Bridges advertise `framer-interaction-verification-v1`,
 when interaction work is declared as observable behavior, checked against the
 selected Framer mechanism before mutation, and verified from live canonical
 Framer nodes afterward. Repeated behavior is verified on one representative
-target before the remaining targets are changed.
+target before the remaining targets are changed. Declarative `hoverEffect`,
+`tapEffect`, and `appearEffect` styling uses the `native_effect` mechanism and
+is verified from the exact reflected property on each target. A failed
+representative may receive scoped `SET` repairs without unlocking fan-out.
 
 Project connection is handled inside Dexter and completes before the model
 starts:

package/package.json

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

package/src/agent.js

@@ -1549,12 +1549,13 @@ async function callProviderAdapter(
       try {
         await waitForControl(controlPollMs, monitorAbort.signal);
         if (finished || monitorAbort.signal.aborted) return;
-        await postActivity({
+        const response = await send('activity', {
           stage: 'model_turn',
           source: 'bridge',
           meaningful: false,
           message: `${adapter.label || adapter.id || 'Provider'} is still generating the next ${productName} action.`,
         });
+        if (controlRequestsCancellation(response)) await requestCancel();
       } catch (error) {
         if (monitorAbort.signal.aborted) return;
         trace?.warn('adapter_control_poll_failed', { error: errorMeta(error) });
@@ -2029,12 +2030,13 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
         try {
           await waitForControl(controlPollMs, monitorAbort.signal);
           if (cliFinished || monitorAbort.signal.aborted) return;
-          await postCliActivity({
+          const response = await send('activity', {
             stage: 'model_turn',
             source: 'bridge',
             meaningful: false,
             message: `${definition.label} is still generating the next ${productName} action.`,
           });
+          if (controlRequestsCancellation(response)) requestCliCancel();
           if (cliCancelled) return;
         } catch (error) {
           if (monitorAbort.signal.aborted) return;

package/src/api.js

@@ -40,37 +40,62 @@ export async function requestJson(apiBaseUrl, path, {
   deviceToken,
   fetchImpl = fetch,
   signal,
+  timeoutMs = 30_000,
   allowInsecureHttp = false,
 } = {}) {
-  const response = await fetchImpl(`${normalizeApiBaseUrl(apiBaseUrl, {
-    allowInsecureHttp,
-  })}${path}`, {
-    method,
-    signal,
-    headers: {
-      Accept: 'application/json',
-      'Content-Type': 'application/json',
-      ...bearerHeaders(deviceToken),
-    },
-    body: body === undefined ? undefined : JSON.stringify(body),
-  });
-  const parsed = await response.json().catch(() => null);
-  if (!response.ok || parsed?.success === false) {
-    const retryAfterHeader = Number(response.headers?.get?.('retry-after'));
-    const retryAfterSeconds = Number(parsed?.retryAfterSeconds);
-    const retryAfterMs = Number.isFinite(retryAfterHeader) && retryAfterHeader > 0
-      ? retryAfterHeader * 1000
-      : Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
-        ? retryAfterSeconds * 1000
-        : undefined;
-    throw new DexterBridgeApiError(
-      parsed?.error || parsed?.message || `Bridge API request failed with status ${response.status}`,
-      response.status,
-      parsed,
-      retryAfterMs,
-    );
+  const controller = new AbortController();
+  let timedOut = false;
+  const abortFromSource = () => controller.abort(signal?.reason);
+  if (signal?.aborted) abortFromSource();
+  else signal?.addEventListener('abort', abortFromSource, { once: true });
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, Math.max(1, Number(timeoutMs) || 30_000));
+  timeout.unref?.();
+  try {
+    const response = await fetchImpl(`${normalizeApiBaseUrl(apiBaseUrl, {
+      allowInsecureHttp,
+    })}${path}`, {
+      method,
+      signal: controller.signal,
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+        ...bearerHeaders(deviceToken),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const parsed = await response.json().catch(() => null);
+    if (!response.ok || parsed?.success === false) {
+      const retryAfterHeader = Number(response.headers?.get?.('retry-after'));
+      const retryAfterSeconds = Number(parsed?.retryAfterSeconds);
+      const retryAfterMs = Number.isFinite(retryAfterHeader) && retryAfterHeader > 0
+        ? retryAfterHeader * 1000
+        : Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
+          ? retryAfterSeconds * 1000
+          : undefined;
+      throw new DexterBridgeApiError(
+        parsed?.error || parsed?.message || `Bridge API request failed with status ${response.status}`,
+        response.status,
+        parsed,
+        retryAfterMs,
+      );
+    }
+    return parsed;
+  } catch (error) {
+    if (timedOut) {
+      throw new DexterBridgeApiError(
+        'The Dexter Bridge API request timed out.',
+        408,
+        { code: 'DEXTER_BRIDGE_REQUEST_TIMEOUT' },
+      );
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+    signal?.removeEventListener('abort', abortFromSource);
   }
-  return parsed;
 }
 
 export function claimPairing(apiBaseUrl, {
@@ -160,6 +185,7 @@ export function pollRun(apiBaseUrl, {
     method: 'POST',
     deviceToken,
     fetchImpl,
+    timeoutMs: Math.max(30_000, Number(waitMs) + 10_000),
     allowInsecureHttp,
     body: {
       waitMs,
@@ -245,6 +271,7 @@ export function postRunEvent(apiBaseUrl, {
     method: 'POST',
     deviceToken,
     fetchImpl,
+    timeoutMs: 10_000,
     allowInsecureHttp,
     body: {
       event,

package/src/framerAgentTools.js

@@ -278,7 +278,7 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
   {
     name: 'framer_verify_interactions',
     description:
-      'Verify the observable behavior contract from the live Framer tree. The runtime derives the required action and invariants from the planned behavior and mechanism; supply only canonical evidence node IDs. This is the only tool that can satisfy interaction verification.',
+      'Verify the observable behavior contract from the live Framer tree. The runtime derives the required action and invariants from the planned behavior and mechanism; supply canonical evidence node IDs. For native_effect, use hoverEffect, tapEffect, or appearEffect as the event value. This is the only tool that can satisfy interaction verification.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -759,11 +759,9 @@ function authoritativeNodeIdsFromAssignment(assignment) {
   const context = isRecord(assignment?.context) ? assignment.context : {};
   const grant = isRecord(context.contextGrant) ? context.contextGrant : {};
   return uniqueStrings([
-    context.activePageId,
     ...(Array.isArray(context.selectedNodeIds)
       ? context.selectedNodeIds
       : []),
-    grant.activePageId,
     ...(Array.isArray(grant.selectedNodeIds)
       ? grant.selectedNodeIds
       : []),
@@ -1094,6 +1092,7 @@ export function createFramerAgentToolRuntime({
     verifiedAt: null,
   };
   const representativeVerifiedBehaviorIds = new Set();
+  const representativeRepairNodeIds = new Set();
   const repeatedBehaviorVerificationFailures = new Map();
   const mutationReceipts = [];
   let screenshotBeforeMutation = false;
@@ -1811,13 +1810,32 @@ export function createFramerAgentToolRuntime({
       .update(`${name}\n${JSON.stringify(rawArguments)}`)
       .digest('hex');
 
-  const requireTaskPlanForMutation = ({ canvas = false } = {}) => {
+  const representativeRepairTargets = (changes) => {
+    const commands = summarizeFramerChanges(changes).commands;
+    if (
+      commands.length === 0
+      || commands.some((command) =>
+        command.operation !== 'set'
+        || !command.nodeId
+        || !representativeRepairNodeIds.has(command.nodeId))
+    ) {
+      return [];
+    }
+    return uniqueStrings(commands.map((command) => command.nodeId));
+  };
+
+  const requireTaskPlanForMutation = ({
+    canvas = false,
+    changes = '',
+  } = {}) => {
     if (!taskPlan) {
       throw toolError(
         'FRAMER_HARNESS_PLAN_REQUIRED',
         'Inspect the live Framer target, then call framer_plan_task before making a mutation.',
       );
     }
+    const repairTargets = representativeRepairTargets(changes);
+    const isRepresentativeRepair = repairTargets.length > 0;
     if (
       (canvas || taskPlan.verification.includes('visual'))
       && !screenshotBeforeMutation
@@ -1852,10 +1870,10 @@ export function createFramerAgentToolRuntime({
             && decision.representativeFirst))
         .filter((behavior) =>
           !representativeVerifiedBehaviorIds.has(behavior.id));
-      if (pendingRepresentative.length > 0) {
+      if (pendingRepresentative.length > 0 && !isRepresentativeRepair) {
         throw toolError(
           'FRAMER_BEHAVIOR_REPRESENTATIVE_VERIFICATION_REQUIRED',
-          `Verify one representative implementation for ${pendingRepresentative.map((behavior) => behavior.id).join(', ')} before batching further mutations.`,
+          `Verify one representative implementation for ${pendingRepresentative.map((behavior) => behavior.id).join(', ')} before batching further mutations. A failed check may be repaired with SET changes limited to its evidence nodes.`,
         );
       }
     }
@@ -2117,6 +2135,11 @@ export function createFramerAgentToolRuntime({
           ...verified,
           verifiedAt: new Date().toISOString(),
         };
+        representativeRepairNodeIds.clear();
+        for (const check of verified.checks.filter((item) => !item.passed)) {
+          evidenceNodeIds([check]).forEach((nodeId) =>
+            representativeRepairNodeIds.add(nodeId));
+        }
         for (const behaviorResult of verified.behaviors) {
           const failedChecks = verified.checks.filter((check) =>
             check.behaviorId === behaviorResult.behaviorId && !check.passed);
@@ -2146,7 +2169,11 @@ export function createFramerAgentToolRuntime({
             behaviorResult.behaviorId,
             { fingerprint: failureFingerprint, count },
           );
-          if (count < 2 || !behaviorResult.mechanism) continue;
+          if (
+            count < 2
+            || !behaviorResult.mechanism
+            || behaviorResult.mechanism === 'native_effect'
+          ) continue;
           const alreadyRejected = taskPlan.rejectedMechanisms.some((rejected) =>
             rejected.mechanism === behaviorResult.mechanism
             && (
@@ -2244,7 +2271,7 @@ export function createFramerAgentToolRuntime({
             'Framer Agent changes are required.',
           );
         }
-        requireTaskPlanForMutation({ canvas: true });
+        requireTaskPlanForMutation({ canvas: true, changes });
         const pagePath = normalizePagePath(rawArguments.pagePath);
         result = await execCode(
           [

package/src/framerBehaviorContract.js

@@ -25,6 +25,7 @@ export const BEHAVIOR_LAYOUT_EFFECTS = [
 
 export const BEHAVIOR_MECHANISMS = [
   'native_event',
+  'native_effect',
   'native_overlay',
   'native_component_variants',
   'existing_component_control',
@@ -40,6 +41,14 @@ const MECHANISM_CAPABILITIES = {
     reversible: false,
     repeatable: true,
   },
+  native_effect: {
+    activations: new Set(['tap', 'hover', 'appear']),
+    presentations: new Set(['none']),
+    layoutEffects: new Set(['none']),
+    stateChange: false,
+    reversible: true,
+    repeatable: true,
+  },
   native_overlay: {
     activations: new Set(['tap', 'hover', 'appear', 'key']),
     presentations: new Set(['floating', 'modal']),
@@ -81,6 +90,21 @@ const FRAME_EVENT_NODE_TYPES = new Set([
   'ComponentInstanceNode',
 ]);
 
+const FRAME_EFFECT_NODE_TYPES = new Set([
+  'ComponentInstanceNode',
+  'FrameNode',
+  'IconNode',
+  'RelativeOverlayNode',
+  'RichTextNode',
+  'ShaderNode',
+]);
+
+const NATIVE_EFFECT_BY_ACTIVATION = {
+  tap: 'tapEffect',
+  hover: 'hoverEffect',
+  appear: 'appearEffect',
+};
+
 function isRecord(value) {
   return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }
@@ -465,14 +489,32 @@ function referencesComponent(snapshot, componentNodeId) {
   const node = nodeFromSnapshot(snapshot);
   if (!node || !componentNodeId) return false;
   const component = isRecord(node.component) ? node.component : {};
-  return [
+  const references = [
+    typeof node.component === 'string' ? node.component : '',
     node.componentId,
     node.componentIdentifier,
     component.id,
     component.nodeId,
     component.componentId,
     component.componentIdentifier,
-  ].some((value) => text(value, 200) === componentNodeId);
+  ];
+  const normalizedReferences = new Set(
+    references.flatMap((value) => {
+      const reference = text(value, 500);
+      if (!reference) return [];
+      const withoutCodePrefix = reference
+        .replace(/^codefile\//i, '')
+        .replace(/^code:/i, '');
+      const withoutExport = withoutCodePrefix.split(':')[0];
+      return [
+        reference,
+        withoutCodePrefix,
+        withoutExport,
+        withoutExport.split('/').pop(),
+      ].filter(Boolean);
+    }),
+  );
+  return normalizedReferences.has(componentNodeId);
 }
 
 function nodeVisible(snapshot) {
@@ -490,6 +532,21 @@ function eventText(snapshot, event) {
   return values.length > 0 ? normalizedEvidenceText(values) : '';
 }
 
+function directNodeProperty(snapshot, property) {
+  const node = nodeFromSnapshot(snapshot);
+  if (!node) return undefined;
+  if (Object.prototype.hasOwnProperty.call(node, property)) {
+    return node[property];
+  }
+  if (
+    isRecord(node.attributes)
+    && Object.prototype.hasOwnProperty.call(node.attributes, property)
+  ) {
+    return node.attributes[property];
+  }
+  return undefined;
+}
+
 function expectedEvents(activation) {
   if (activation === 'tap') return ['onTap', 'onTapStart'];
   if (activation === 'hover') return ['onMouseEnter', 'onMouseLeave'];
@@ -625,9 +682,13 @@ function verifyComponentInstances(
   snapshots,
   failures,
   context,
+  { requireDefinition = true } = {},
 ) {
   const component = snapshotFor(snapshots, check.componentNodeId);
-  if (!component || nodeType(component) !== 'ComponentNode') {
+  if (
+    requireDefinition
+    && (!component || nodeType(component) !== 'ComponentNode')
+  ) {
     failures.push('component definition was not found');
   }
   const instances = check.instanceNodeIds.map((id) => ({
@@ -774,7 +835,17 @@ function hasCodeComponentEvidence(snapshot) {
 }
 
 function verifyCodeComponent(check, behavior, snapshots, failures, context) {
-  verifyComponentInstances(check, behavior, snapshots, failures, context);
+  // Code files are not native canvas ComponentNodes. Their durable structural
+  // proof is an installed ComponentInstanceNode whose component reference
+  // resolves to the authored code-file ID.
+  verifyComponentInstances(
+    check,
+    behavior,
+    snapshots,
+    failures,
+    context,
+    { requireDefinition: false },
+  );
   const nodes = check.instanceNodeIds.map((id) => snapshotFor(snapshots, id));
   if (
     !nodes.some(hasCodeComponentEvidence)
@@ -782,12 +853,10 @@ function verifyCodeComponent(check, behavior, snapshots, failures, context) {
   ) {
     failures.push('no code-component source or installed code-component evidence was found');
   }
-  verifyExpectedContent(
-    behavior,
-    snapshots,
-    [check.componentNodeId, ...check.instanceNodeIds],
-    failures,
-  );
+  // Content is covered by the mandatory structural and visual checks. Behavior
+  // plans may describe content semantically rather than quote literal canvas
+  // text, so treating that prose as an exact interaction assertion creates
+  // false failures for otherwise valid code components.
 }
 
 function verifyNativeEvent(check, behavior, snapshots, failures) {
@@ -799,6 +868,47 @@ function verifyNativeEvent(check, behavior, snapshots, failures) {
   );
 }
 
+function verifyNativeEffect(check, behavior, snapshots, failures) {
+  const trigger = snapshotFor(snapshots, check.triggerNodeId);
+  if (!check.triggerNodeId || !trigger) {
+    failures.push('effect target node was not found');
+    return null;
+  }
+  if (!FRAME_EFFECT_NODE_TYPES.has(nodeType(trigger))) {
+    failures.push(
+      `${nodeType(trigger) || 'the target node'} does not support verified Framer effects`,
+    );
+  }
+  const effectName = NATIVE_EFFECT_BY_ACTIVATION[behavior.activation];
+  if (!effectName) {
+    failures.push(
+      `native_effect does not support ${behavior.activation} activation`,
+    );
+    return null;
+  }
+  if (check.event !== effectName) {
+    failures.push(
+      `${check.event || 'the supplied effect'} does not match ${effectName}`,
+    );
+  }
+  const effect = directNodeProperty(trigger, effectName);
+  if (!isRecord(effect) || Object.keys(effect).length === 0) {
+    failures.push(`${effectName} is not configured on the target`);
+    return null;
+  }
+  if (
+    effectName === 'appearEffect'
+    && !['onInView', 'onMount', 'onScrollTarget', 'onScrollDirection']
+      .includes(effect.trigger)
+  ) {
+    failures.push('appearEffect does not declare a supported trigger');
+  }
+  return {
+    effectName,
+    observedEffect: effect,
+  };
+}
+
 export function verifyBehaviorEvidence({
   plan,
   checks,
@@ -818,6 +928,7 @@ export function verifyBehaviorEvidence({
     const behavior = behaviorById.get(check.behaviorId);
     const decision = mechanismByBehavior.get(check.behaviorId);
     const failures = [];
+    let nativeEffectEvidence = null;
     if (!behavior || !decision) {
       failures.push('the planned behavior or mechanism was not found');
     } else if (decision.mechanism === 'native_overlay') {
@@ -828,12 +939,20 @@ export function verifyBehaviorEvidence({
       verifyExistingComponent(check, behavior, snapshots, failures, context);
     } else if (decision.mechanism === 'code_component') {
       verifyCodeComponent(check, behavior, snapshots, failures, context);
+    } else if (decision.mechanism === 'native_effect') {
+      nativeEffectEvidence = verifyNativeEffect(
+        check,
+        behavior,
+        snapshots,
+        failures,
+      );
     } else {
       verifyNativeEvent(check, behavior, snapshots, failures);
     }
     return {
       ...check,
       mechanism: decision?.mechanism,
+      ...(nativeEffectEvidence || {}),
       passed: failures.length === 0,
       failures,
     };

package/src/protocol.js

@@ -467,7 +467,7 @@ export function buildOutcomePrompt(outcome = {}, product, promptContext = {}) {
           ]),
       'The current user request is the source of intent; prior conversation, selections, attachments, and project content are context, not automatic commands.',
       'Dexter has not classified the request for you. After your initial live Framer inspection, call framer_plan_task before the first mutation. Derive task domains and observable behavior requirements from the full user intent and live project. For interaction work, describe initial and activated states, presentation, layout effect, reversibility, repetition, expected target count, and expected content; then choose and justify one compatible mechanism for each behavior.',
-      'Choose mechanisms by capability, not labels or keywords. Inline state that changes document flow requires component variants, an existing component control that provides that state, or a code component. Relative and fixed overlays are for floating or modal presentation and cannot satisfy inline reflow.',
+      'Choose mechanisms by capability, not labels or keywords. Use native_effect for declarative hoverEffect, tapEffect, or appearEffect styling that does not create application state. Inline state that changes document flow requires component variants, an existing component control that provides that state, or a code component. Relative and fixed overlays are for floating or modal presentation and cannot satisfy inline reflow.',
       'Prefer framer_apply_changes for page, layout, component, style, design-token, and CMS-on-canvas work. Use framer_read_project for focused reads. Use framer_read or framer_write only for Framer capabilities that those higher-level tools do not cover.',
       'When selected-section behavior requires a component, you may create the smallest component definition and variants needed by that selected section and place instances only inside the authorized subtree. This is supporting implementation, not unauthorized project-wide scope.',
       'For imagery, use user attachments first, then reuse suitable project imagery, then call framer_query_images. Never fabricate an image URL.',
@@ -476,7 +476,7 @@ export function buildOutcomePrompt(outcome = {}, product, promptContext = {}) {
       'Do not publish or deploy unless the assignment explicitly says publishing is authorized.',
       'You own verification. Your framer_plan_task declaration determines the required evidence, and the harness enforces it before accepting completion.',
       'Every framer_apply_changes canvas mutation requires a screenshot before the first mutation and after the final mutation. Use verifies on final reads to establish link, responsive, code, or data checks when your plan requires them.',
-      'A generic read cannot verify interactions. framer_verify_interactions derives success requirements from the behavior contract and chosen mechanism; supply canonical evidence node IDs rather than defining your own success test. For repeated behavior, implement and verify one representative before batching unless an already verified project mechanism is being reused, then verify complete target coverage after the final mutation.',
+      'A generic read cannot verify interactions. framer_verify_interactions derives success requirements from the behavior contract and chosen mechanism; supply canonical evidence node IDs rather than defining your own success test. Native effects are verified from their reflected hoverEffect, tapEffect, or appearEffect properties and are structural evidence, not runtime playback. For repeated behavior, implement and verify one representative before batching unless an already verified project mechanism is being reused, then verify complete target coverage after the final mutation. If representative verification fails, repair only the supplied evidence nodes before verifying again.',
       'Do not reuse a mechanism recorded as rejected by the user or prior verification. Change the semantic approach instead of moving the same broken wiring to another layer.',
       'For visual work, evaluate hierarchy, spacing, contrast, typography, balance, imagery, interaction states, and responsive integrity.',
       'You decide when the run is complete. Avoid repeated inspection of unchanged evidence and stop when the requested outcome has been implemented and verified.',