@gakim-digital/dexter-bridge 0.5.21 → 0.11.1

package/src/framerBehaviorContract.js

@@ -0,0 +1,962 @@
+import crypto from 'node:crypto';
+
+export const BEHAVIOR_ACTIVATIONS = [
+  'tap',
+  'hover',
+  'submit',
+  'appear',
+  'key',
+];
+
+export const BEHAVIOR_PRESENTATIONS = [
+  'none',
+  'inline',
+  'floating',
+  'modal',
+  'navigation',
+];
+
+export const BEHAVIOR_LAYOUT_EFFECTS = [
+  'none',
+  'reflow',
+  'overlay',
+  'navigation',
+];
+
+export const BEHAVIOR_MECHANISMS = [
+  'native_event',
+  'native_overlay',
+  'native_component_variants',
+  'existing_component_control',
+  'code_component',
+];
+
+const MECHANISM_CAPABILITIES = {
+  native_event: {
+    activations: new Set(['tap', 'hover', 'appear', 'key']),
+    presentations: new Set(['none', 'navigation']),
+    layoutEffects: new Set(['none', 'navigation']),
+    stateChange: false,
+    reversible: false,
+    repeatable: true,
+  },
+  native_overlay: {
+    activations: new Set(['tap', 'hover', 'appear', 'key']),
+    presentations: new Set(['floating', 'modal']),
+    layoutEffects: new Set(['overlay']),
+    stateChange: true,
+    reversible: true,
+    repeatable: true,
+  },
+  native_component_variants: {
+    activations: new Set(['tap', 'hover', 'appear', 'key']),
+    presentations: new Set(['none', 'inline']),
+    layoutEffects: new Set(['none', 'reflow']),
+    stateChange: true,
+    reversible: true,
+    repeatable: true,
+  },
+  existing_component_control: {
+    activations: new Set(BEHAVIOR_ACTIVATIONS),
+    presentations: new Set(BEHAVIOR_PRESENTATIONS),
+    layoutEffects: new Set(BEHAVIOR_LAYOUT_EFFECTS),
+    stateChange: true,
+    reversible: true,
+    repeatable: true,
+  },
+  code_component: {
+    activations: new Set(BEHAVIOR_ACTIVATIONS),
+    presentations: new Set(BEHAVIOR_PRESENTATIONS),
+    layoutEffects: new Set(BEHAVIOR_LAYOUT_EFFECTS),
+    stateChange: true,
+    reversible: true,
+    repeatable: true,
+  },
+};
+
+const FRAME_EVENT_NODE_TYPES = new Set([
+  'FrameNode',
+  'RichTextNode',
+  'IconNode',
+  'ComponentInstanceNode',
+]);
+
+function isRecord(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function text(value, maximum = 500) {
+  return typeof value === 'string'
+    ? value.trim().slice(0, maximum)
+    : '';
+}
+
+function uniqueStrings(values, maximum = 50) {
+  return Array.from(new Set(
+    (Array.isArray(values) ? values : [])
+      .map((value) => text(value, 500))
+      .filter(Boolean),
+  )).slice(0, maximum);
+}
+
+function integer(value, fallback = 1, minimum = 1, maximum = 50) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed)
+    ? Math.min(maximum, Math.max(minimum, Math.floor(parsed)))
+    : fallback;
+}
+
+function contractError(code, message) {
+  return Object.assign(new Error(message), { code, statusCode: 400 });
+}
+
+export function behaviorSignature(behavior) {
+  return crypto
+    .createHash('sha256')
+    .update(JSON.stringify({
+      activation: behavior.activation,
+      presentation: behavior.presentation,
+      stateChange: behavior.stateChange,
+      layoutEffect: behavior.layoutEffect,
+      reversible: behavior.reversible,
+      repeatable: behavior.repeatable,
+      expectedTargets: behavior.expectedTargets,
+      initialState: behavior.initialState,
+      activatedState: behavior.activatedState,
+    }))
+    .digest('hex');
+}
+
+function normalizeBehavior(rawBehavior, index) {
+  if (!isRecord(rawBehavior)) {
+    throw contractError(
+      'FRAMER_BEHAVIOR_CONTRACT_INVALID',
+      `Behavior ${index + 1} must be an object.`,
+    );
+  }
+  const id = text(rawBehavior.id, 120);
+  const description = text(rawBehavior.description, 500);
+  const triggerDescription = text(rawBehavior.triggerDescription, 300);
+  const activation = text(rawBehavior.activation, 40);
+  const presentation = text(rawBehavior.presentation, 40);
+  const layoutEffect = text(rawBehavior.layoutEffect, 40);
+  const initialState = text(rawBehavior.initialState, 300);
+  const activatedState = text(rawBehavior.activatedState, 300);
+  if (
+    !id
+    || description.length < 5
+    || triggerDescription.length < 3
+    || !BEHAVIOR_ACTIVATIONS.includes(activation)
+    || !BEHAVIOR_PRESENTATIONS.includes(presentation)
+    || !BEHAVIOR_LAYOUT_EFFECTS.includes(layoutEffect)
+    || !initialState
+    || !activatedState
+  ) {
+    throw contractError(
+      'FRAMER_BEHAVIOR_CONTRACT_INVALID',
+      `Behavior ${index + 1} must declare its identity, trigger, activation, presentation, initial state, activated state, and layout effect.`,
+    );
+  }
+  const behavior = {
+    id,
+    description,
+    triggerDescription,
+    activation,
+    presentation,
+    stateChange: rawBehavior.stateChange === true,
+    layoutEffect,
+    reversible: rawBehavior.reversible === true,
+    repeatable: rawBehavior.repeatable === true,
+    expectedTargets: integer(rawBehavior.expectedTargets),
+    expectedContent: uniqueStrings(rawBehavior.expectedContent, 20),
+    initialState,
+    activatedState,
+  };
+  return {
+    ...behavior,
+    signature: behaviorSignature(behavior),
+  };
+}
+
+function normalizeMechanism(rawMechanism, index) {
+  if (!isRecord(rawMechanism)) {
+    throw contractError(
+      'FRAMER_BEHAVIOR_MECHANISM_INVALID',
+      `Mechanism ${index + 1} must be an object.`,
+    );
+  }
+  const behaviorId = text(rawMechanism.behaviorId, 120);
+  const mechanism = text(rawMechanism.mechanism, 80);
+  const rationale = text(rawMechanism.rationale, 800);
+  if (
+    !behaviorId
+    || !BEHAVIOR_MECHANISMS.includes(mechanism)
+    || rationale.length < 10
+  ) {
+    throw contractError(
+      'FRAMER_BEHAVIOR_MECHANISM_INVALID',
+      `Mechanism ${index + 1} must identify a behavior, a supported mechanism, and a concrete rationale.`,
+    );
+  }
+  return {
+    behaviorId,
+    mechanism,
+    rationale,
+    representativeFirst: rawMechanism.representativeFirst !== false,
+  };
+}
+
+export function normalizeRejectedMechanisms(values) {
+  return (Array.isArray(values) ? values : [])
+    .slice(0, 30)
+    .flatMap((raw, index) => {
+      if (!isRecord(raw)) return [];
+      const behaviorId = text(raw.behaviorId, 120);
+      const behaviorSignatureValue = text(raw.behaviorSignature, 128);
+      const mechanism = text(raw.mechanism, 80);
+      const reason = text(raw.reason, 800);
+      if (
+        (!behaviorId && !behaviorSignatureValue)
+        || !BEHAVIOR_MECHANISMS.includes(mechanism)
+        || reason.length < 5
+      ) {
+        throw contractError(
+          'FRAMER_REJECTED_MECHANISM_INVALID',
+          `Rejected mechanism ${index + 1} must identify a behavior or signature, a supported mechanism, and a reason.`,
+        );
+      }
+      return [{
+        ...(behaviorId ? { behaviorId } : {}),
+        ...(behaviorSignatureValue
+          ? { behaviorSignature: behaviorSignatureValue }
+          : {}),
+        mechanism,
+        reason,
+        source:
+          raw.source === 'user_reported_failure'
+          || raw.source === 'verification_failure'
+            ? raw.source
+            : 'verification_failure',
+      }];
+    });
+}
+
+export function mechanismCompatibility(behavior, mechanism) {
+  const capabilities = MECHANISM_CAPABILITIES[mechanism];
+  if (!capabilities) {
+    return {
+      compatible: false,
+      failures: [`Unknown behavior mechanism ${mechanism}.`],
+    };
+  }
+  const failures = [];
+  if (!capabilities.activations.has(behavior.activation)) {
+    failures.push(`${mechanism} does not support ${behavior.activation} activation`);
+  }
+  if (!capabilities.presentations.has(behavior.presentation)) {
+    failures.push(`${mechanism} does not support ${behavior.presentation} presentation`);
+  }
+  if (!capabilities.layoutEffects.has(behavior.layoutEffect)) {
+    failures.push(`${mechanism} does not support ${behavior.layoutEffect} layout behavior`);
+  }
+  if (behavior.stateChange && !capabilities.stateChange) {
+    failures.push(`${mechanism} cannot provide state changes`);
+  }
+  if (behavior.reversible && !capabilities.reversible) {
+    failures.push(`${mechanism} cannot provide reversible behavior`);
+  }
+  if (behavior.repeatable && !capabilities.repeatable) {
+    failures.push(`${mechanism} cannot be repeated across targets`);
+  }
+  return {
+    compatible: failures.length === 0,
+    failures,
+  };
+}
+
+export function normalizeBehaviorPlan(rawArguments, inheritedRejected = []) {
+  const behaviors = (Array.isArray(rawArguments.behaviors)
+    ? rawArguments.behaviors
+    : []).slice(0, 20).map(normalizeBehavior);
+  const mechanisms = (Array.isArray(rawArguments.mechanisms)
+    ? rawArguments.mechanisms
+    : []).slice(0, 20).map(normalizeMechanism);
+  const rejectedMechanisms = [
+    ...normalizeRejectedMechanisms(inheritedRejected),
+    ...normalizeRejectedMechanisms(rawArguments.rejectedMechanisms),
+  ];
+  const behaviorIds = new Set();
+  for (const behavior of behaviors) {
+    if (behaviorIds.has(behavior.id)) {
+      throw contractError(
+        'FRAMER_BEHAVIOR_CONTRACT_INVALID',
+        `Behavior IDs must be unique; "${behavior.id}" is duplicated.`,
+      );
+    }
+    behaviorIds.add(behavior.id);
+  }
+  const mechanismByBehavior = new Map();
+  for (const decision of mechanisms) {
+    if (!behaviorIds.has(decision.behaviorId)) {
+      throw contractError(
+        'FRAMER_BEHAVIOR_MECHANISM_INVALID',
+        `Mechanism references unknown behavior "${decision.behaviorId}".`,
+      );
+    }
+    if (mechanismByBehavior.has(decision.behaviorId)) {
+      throw contractError(
+        'FRAMER_BEHAVIOR_MECHANISM_INVALID',
+        `Behavior "${decision.behaviorId}" has more than one selected mechanism.`,
+      );
+    }
+    mechanismByBehavior.set(decision.behaviorId, decision);
+  }
+  const compatibility = behaviors.map((behavior) => {
+    const decision = mechanismByBehavior.get(behavior.id);
+    if (!decision) {
+      throw contractError(
+        'FRAMER_BEHAVIOR_MECHANISM_REQUIRED',
+        `Behavior "${behavior.id}" requires one explicit implementation mechanism.`,
+      );
+    }
+    const rejected = rejectedMechanisms.find((item) =>
+      item.mechanism === decision.mechanism
+      && (
+        item.behaviorId === behavior.id
+        || item.behaviorSignature === behavior.signature
+      ));
+    if (rejected) {
+      throw contractError(
+        'FRAMER_BEHAVIOR_MECHANISM_REJECTED',
+        `${decision.mechanism} was already rejected for behavior "${behavior.id}": ${rejected.reason}`,
+      );
+    }
+    const result = mechanismCompatibility(behavior, decision.mechanism);
+    if (!result.compatible) {
+      throw contractError(
+        'FRAMER_BEHAVIOR_MECHANISM_INCOMPATIBLE',
+        `The selected mechanism for behavior "${behavior.id}" is incompatible: ${result.failures.join('; ')}.`,
+      );
+    }
+    return {
+      behaviorId: behavior.id,
+      behaviorSignature: behavior.signature,
+      mechanism: decision.mechanism,
+      compatible: true,
+      requiredCapabilities: behaviorCapabilities(behavior),
+    };
+  });
+  return {
+    behaviors,
+    mechanisms,
+    rejectedMechanisms,
+    compatibility,
+  };
+}
+
+export function behaviorCapabilities(behavior) {
+  return [
+    `activation:${behavior.activation}`,
+    `presentation:${behavior.presentation}`,
+    `layout:${behavior.layoutEffect}`,
+    ...(behavior.stateChange ? ['state-change'] : []),
+    ...(behavior.reversible ? ['reversible'] : []),
+    ...(behavior.repeatable ? ['repeatable'] : []),
+  ];
+}
+
+export function mergeBehaviorPlans(current, next) {
+  if (!current) return next;
+  const byId = new Map(current.behaviors.map((item) => [item.id, item]));
+  next.behaviors.forEach((item) => byId.set(item.id, item));
+  const mechanisms = new Map(
+    current.mechanisms.map((item) => [item.behaviorId, item]),
+  );
+  next.mechanisms.forEach((item) => mechanisms.set(item.behaviorId, item));
+  const merged = {
+    behaviors: [...byId.values()],
+    mechanisms: [...mechanisms.values()],
+    rejectedMechanisms: [
+      ...current.rejectedMechanisms,
+      ...next.rejectedMechanisms,
+    ],
+  };
+  return normalizeBehaviorPlan(merged);
+}
+
+function normalizedEvidenceText(value) {
+  try {
+    return JSON.stringify(value).toLowerCase();
+  } catch {
+    return '';
+  }
+}
+
+function eventEvidenceValues(value, event) {
+  const matches = [];
+  const expected = event.toLowerCase();
+  const visit = (current) => {
+    if (Array.isArray(current)) {
+      current.forEach(visit);
+      return;
+    }
+    if (!isRecord(current)) return;
+    for (const [key, nested] of Object.entries(current)) {
+      const normalizedKey = key.toLowerCase();
+      if (
+        normalizedKey === expected
+        || normalizedKey.startsWith(`${expected}.`)
+      ) {
+        matches.push(nested);
+      }
+      visit(nested);
+    }
+  };
+  visit(value);
+  return matches;
+}
+
+function snapshotFor(snapshots, id) {
+  if (!id) return null;
+  if (snapshots instanceof Map) return snapshots.get(id) || null;
+  return snapshots?.[id] || null;
+}
+
+function nodeFromSnapshot(snapshot) {
+  return isRecord(snapshot?.node) ? snapshot.node : snapshot;
+}
+
+function nodeType(snapshot) {
+  const node = nodeFromSnapshot(snapshot);
+  return text(node?.type || node?.nodeType, 80);
+}
+
+function parentId(snapshot) {
+  const node = nodeFromSnapshot(snapshot);
+  return text(
+    snapshot?.parentId
+    || node?.parentId
+    || node?.parent?.id,
+    200,
+  );
+}
+
+function ancestorIds(snapshot) {
+  const node = nodeFromSnapshot(snapshot);
+  return uniqueStrings([
+    ...(Array.isArray(snapshot?.ancestorIds) ? snapshot.ancestorIds : []),
+    ...(Array.isArray(node?.ancestorIds) ? node.ancestorIds : []),
+    ...(Array.isArray(node?.ancestors)
+      ? node.ancestors.map((ancestor) =>
+          typeof ancestor === 'string' ? ancestor : ancestor?.id)
+      : []),
+  ], 100);
+}
+
+function belongsTo(snapshot, expectedAncestorId) {
+  if (!snapshot || !expectedAncestorId) return false;
+  return (
+    parentId(snapshot) === expectedAncestorId
+    || ancestorIds(snapshot).includes(expectedAncestorId)
+  );
+}
+
+function referencesComponent(snapshot, componentNodeId) {
+  const node = nodeFromSnapshot(snapshot);
+  if (!node || !componentNodeId) return false;
+  const component = isRecord(node.component) ? node.component : {};
+  return [
+    node.componentId,
+    node.componentIdentifier,
+    component.id,
+    component.nodeId,
+    component.componentId,
+    component.componentIdentifier,
+  ].some((value) => text(value, 200) === componentNodeId);
+}
+
+function nodeVisible(snapshot) {
+  const node = nodeFromSnapshot(snapshot);
+  if (!node) return null;
+  if (node.visible === false || node.hidden === true) return false;
+  if (node.visible === true || node.hidden === false) return true;
+  return true;
+}
+
+function eventText(snapshot, event) {
+  const node = nodeFromSnapshot(snapshot);
+  if (!node) return '';
+  const values = eventEvidenceValues(node, event);
+  return values.length > 0 ? normalizedEvidenceText(values) : '';
+}
+
+function expectedEvents(activation) {
+  if (activation === 'tap') return ['onTap', 'onTapStart'];
+  if (activation === 'hover') return ['onMouseEnter', 'onMouseLeave'];
+  if (activation === 'appear') return ['onAppear'];
+  if (activation === 'key') return ['onKeyDown'];
+  return [];
+}
+
+function normalizeEvidence(raw, behaviorById) {
+  if (!isRecord(raw)) {
+    throw contractError(
+      'FRAMER_BEHAVIOR_EVIDENCE_INVALID',
+      'Interaction evidence must be an object.',
+    );
+  }
+  const behaviorId = text(raw.behaviorId, 120);
+  const behavior = behaviorById.get(behaviorId);
+  if (!behavior) {
+    throw contractError(
+      'FRAMER_BEHAVIOR_EVIDENCE_INVALID',
+      `Interaction evidence references unknown behavior "${behaviorId}".`,
+    );
+  }
+  return {
+    behaviorId,
+    description: text(raw.description, 300),
+    triggerNodeId: text(raw.triggerNodeId, 200),
+    event: text(raw.event, 80),
+    targetNodeId: text(raw.targetNodeId, 200),
+    componentNodeId: text(raw.componentNodeId, 200),
+    instanceNodeIds: uniqueStrings(raw.instanceNodeIds, 50),
+    openVariantNodeId: text(raw.openVariantNodeId, 200),
+    closedVariantNodeId: text(raw.closedVariantNodeId, 200),
+    openAnswerNodeId: text(raw.openAnswerNodeId, 200),
+    closedAnswerNodeId: text(raw.closedAnswerNodeId, 200),
+  };
+}
+
+export function normalizeBehaviorEvidence(rawChecks, plan) {
+  const behaviorById = new Map(
+    (plan?.behaviors || []).map((behavior) => [behavior.id, behavior]),
+  );
+  const checks = (Array.isArray(rawChecks) ? rawChecks : []).slice(0, 50);
+  if (!checks.length) {
+    throw contractError(
+      'FRAMER_BEHAVIOR_EVIDENCE_REQUIRED',
+      'Declare evidence for at least one planned behavior.',
+    );
+  }
+  return checks.map((raw) => normalizeEvidence(raw, behaviorById));
+}
+
+export function evidenceNodeIds(checks) {
+  return uniqueStrings(checks.flatMap((check) => [
+    check.triggerNodeId,
+    check.targetNodeId,
+    check.componentNodeId,
+    check.openVariantNodeId,
+    check.closedVariantNodeId,
+    check.openAnswerNodeId,
+    check.closedAnswerNodeId,
+    ...check.instanceNodeIds,
+  ]), 200);
+}
+
+function verifyTrigger(check, behavior, trigger, failures) {
+  if (!check.triggerNodeId || !trigger) {
+    failures.push('trigger node was not found');
+    return '';
+  }
+  const allowedEvents = expectedEvents(behavior.activation);
+  if (
+    allowedEvents.length > 0
+    && !allowedEvents.includes(check.event)
+  ) {
+    failures.push(
+      `${check.event || 'the supplied event'} does not match ${behavior.activation} activation`,
+    );
+  }
+  if (!check.event) {
+    failures.push('the trigger event was not supplied');
+    return '';
+  }
+  if (!FRAME_EVENT_NODE_TYPES.has(nodeType(trigger))) {
+    failures.push(`${nodeType(trigger) || 'the trigger node'} does not support verified frame events`);
+  }
+  const evidence = eventText(trigger, check.event);
+  if (!evidence) failures.push(`${check.event} is not configured on the trigger`);
+  return evidence;
+}
+
+function verifyExpectedContent(behavior, snapshots, nodeIds, failures) {
+  const combined = normalizedEvidenceText(
+    nodeIds.map((id) => nodeFromSnapshot(snapshotFor(snapshots, id))),
+  );
+  for (const expected of behavior.expectedContent) {
+    if (!combined.includes(expected.toLowerCase())) {
+      failures.push(`expected content was not found: ${expected}`);
+    }
+  }
+}
+
+function verifyOverlay(check, behavior, snapshots, failures) {
+  const trigger = snapshotFor(snapshots, check.triggerNodeId);
+  const target = snapshotFor(snapshots, check.targetNodeId);
+  const triggerEvent = verifyTrigger(check, behavior, trigger, failures);
+  if (!check.targetNodeId || !target) {
+    failures.push('overlay target node was not found');
+    return;
+  }
+  if (!triggerEvent.includes('show_overlay')) {
+    failures.push(`${check.event} does not contain SHOW_OVERLAY`);
+  }
+  if (!triggerEvent.includes(check.targetNodeId.toLowerCase())) {
+    failures.push(`${check.event} does not reference target ${check.targetNodeId}`);
+  }
+  const expectedType =
+    behavior.presentation === 'modal'
+      ? 'FixedOverlayNode'
+      : 'RelativeOverlayNode';
+  if (nodeType(target) !== expectedType) {
+    failures.push(`the behavior requires a ${expectedType}`);
+  }
+  if (parentId(target) !== check.triggerNodeId) {
+    failures.push('the overlay is not parented to its actual trigger');
+  }
+  verifyExpectedContent(behavior, snapshots, [check.targetNodeId], failures);
+}
+
+function verifyComponentInstances(
+  check,
+  behavior,
+  snapshots,
+  failures,
+  context,
+) {
+  const component = snapshotFor(snapshots, check.componentNodeId);
+  if (!component || nodeType(component) !== 'ComponentNode') {
+    failures.push('component definition was not found');
+  }
+  const instances = check.instanceNodeIds.map((id) => ({
+    id,
+    snapshot: snapshotFor(snapshots, id),
+  }));
+  for (const instance of instances) {
+    if (!instance.snapshot || nodeType(instance.snapshot) !== 'ComponentInstanceNode') {
+      failures.push(`component instance ${instance.id} was not found`);
+    } else if (!referencesComponent(instance.snapshot, check.componentNodeId)) {
+      failures.push(`component instance ${instance.id} does not reference ${check.componentNodeId}`);
+    }
+    const authorizedContainerIds = uniqueStrings(
+      context?.authorizedInstanceContainerIds,
+      100,
+    );
+    if (instance.snapshot && authorizedContainerIds.length > 0) {
+      const ancestry = new Set([
+        instance.id,
+        parentId(instance.snapshot),
+        ...(Array.isArray(instance.snapshot.ancestorIds)
+          ? instance.snapshot.ancestorIds
+          : []),
+      ].filter(Boolean));
+      if (!authorizedContainerIds.some((id) => ancestry.has(id))) {
+        failures.push(
+          `component instance ${instance.id} is outside the authorized write scope`,
+        );
+      }
+    }
+  }
+}
+
+function verifyComponentVariants(
+  check,
+  behavior,
+  snapshots,
+  failures,
+  context,
+) {
+  const trigger = snapshotFor(snapshots, check.triggerNodeId);
+  const component = snapshotFor(snapshots, check.componentNodeId);
+  const openVariant = snapshotFor(snapshots, check.openVariantNodeId);
+  const closedVariant = snapshotFor(snapshots, check.closedVariantNodeId);
+  const openAnswer = snapshotFor(snapshots, check.openAnswerNodeId);
+  const closedAnswer = snapshotFor(snapshots, check.closedAnswerNodeId);
+  const triggerEvent = verifyTrigger(check, behavior, trigger, failures);
+  verifyComponentInstances(check, behavior, snapshots, failures, context);
+  if (component && trigger && !belongsTo(trigger, check.componentNodeId)) {
+    failures.push('the trigger is not inside the component definition');
+  }
+  if (
+    !openVariant
+    || !closedVariant
+    || check.openVariantNodeId === check.closedVariantNodeId
+  ) {
+    failures.push('distinct open and closed variants were not found');
+  } else {
+    if (!belongsTo(openVariant, check.componentNodeId)) {
+      failures.push('the open variant does not belong to the component');
+    }
+    if (!belongsTo(closedVariant, check.componentNodeId)) {
+      failures.push('the closed variant does not belong to the component');
+    }
+  }
+  if (!triggerEvent.includes('set_variant')) {
+    failures.push(`${check.event} does not contain SET_VARIANT`);
+  }
+  if (
+    triggerEvent
+    && !triggerEvent.includes('cycle')
+    && !triggerEvent.includes(check.openVariantNodeId.toLowerCase())
+    && !triggerEvent.includes(check.closedVariantNodeId.toLowerCase())
+  ) {
+    failures.push('SET_VARIANT does not reference cycle or a declared variant');
+  }
+  if (!openAnswer || !closedAnswer) {
+    failures.push('open and closed answer-state nodes were not found');
+  } else {
+    if (!belongsTo(openAnswer, check.openVariantNodeId)) {
+      failures.push('the visible answer does not belong to the open variant');
+    }
+    if (!belongsTo(closedAnswer, check.closedVariantNodeId)) {
+      failures.push('the hidden answer does not belong to the closed variant');
+    }
+    if (nodeVisible(openAnswer) === false) {
+      failures.push('the answer is hidden in the open variant');
+    }
+    if (nodeVisible(closedAnswer) !== false) {
+      failures.push('the answer is not hidden in the closed variant');
+    }
+  }
+  verifyExpectedContent(
+    behavior,
+    snapshots,
+    [check.openAnswerNodeId, check.closedAnswerNodeId],
+    failures,
+  );
+}
+
+function verifyExistingComponent(
+  check,
+  behavior,
+  snapshots,
+  failures,
+  context,
+) {
+  const trigger = snapshotFor(snapshots, check.triggerNodeId);
+  const triggerEvent = verifyTrigger(check, behavior, trigger, failures);
+  verifyComponentInstances(check, behavior, snapshots, failures, context);
+  if (trigger && !belongsTo(trigger, check.componentNodeId)) {
+    failures.push('the trigger is not inside the existing component definition');
+  }
+  const permittedActions =
+    behavior.presentation === 'floating' || behavior.presentation === 'modal'
+      ? ['show_overlay', 'trigger_event']
+      : behavior.stateChange
+        ? ['set_variant', 'trigger_event']
+        : [];
+  if (
+    permittedActions.length > 0
+    && !permittedActions.some((action) => triggerEvent.includes(action))
+  ) {
+    failures.push('the component trigger does not expose an action capable of the declared behavior');
+  }
+  verifyExpectedContent(
+    behavior,
+    snapshots,
+    [check.componentNodeId, ...check.instanceNodeIds],
+    failures,
+  );
+}
+
+function hasCodeComponentEvidence(snapshot) {
+  const node = nodeFromSnapshot(snapshot);
+  if (!node) return false;
+  const serialized = normalizedEvidenceText(node);
+  return (
+    serialized.includes('codecomponent')
+    || serialized.includes('code_file')
+    || serialized.includes('codefile')
+    || serialized.includes('componentidentifier')
+  );
+}
+
+function verifyCodeComponent(check, behavior, snapshots, failures, context) {
+  verifyComponentInstances(check, behavior, snapshots, failures, context);
+  const nodes = check.instanceNodeIds.map((id) => snapshotFor(snapshots, id));
+  if (
+    !nodes.some(hasCodeComponentEvidence)
+    && Number(context?.lowLevelWriteCalls || 0) < 1
+  ) {
+    failures.push('no code-component source or installed code-component evidence was found');
+  }
+  verifyExpectedContent(
+    behavior,
+    snapshots,
+    [check.componentNodeId, ...check.instanceNodeIds],
+    failures,
+  );
+}
+
+function verifyNativeEvent(check, behavior, snapshots, failures) {
+  verifyTrigger(
+    check,
+    behavior,
+    snapshotFor(snapshots, check.triggerNodeId),
+    failures,
+  );
+}
+
+export function verifyBehaviorEvidence({
+  plan,
+  checks,
+  snapshots,
+  context = {},
+}) {
+  const behaviorById = new Map(
+    (plan?.behaviors || []).map((behavior) => [behavior.id, behavior]),
+  );
+  const mechanismByBehavior = new Map(
+    (plan?.mechanisms || []).map((decision) => [
+      decision.behaviorId,
+      decision,
+    ]),
+  );
+  const verifiedChecks = checks.map((check) => {
+    const behavior = behaviorById.get(check.behaviorId);
+    const decision = mechanismByBehavior.get(check.behaviorId);
+    const failures = [];
+    if (!behavior || !decision) {
+      failures.push('the planned behavior or mechanism was not found');
+    } else if (decision.mechanism === 'native_overlay') {
+      verifyOverlay(check, behavior, snapshots, failures);
+    } else if (decision.mechanism === 'native_component_variants') {
+      verifyComponentVariants(check, behavior, snapshots, failures, context);
+    } else if (decision.mechanism === 'existing_component_control') {
+      verifyExistingComponent(check, behavior, snapshots, failures, context);
+    } else if (decision.mechanism === 'code_component') {
+      verifyCodeComponent(check, behavior, snapshots, failures, context);
+    } else {
+      verifyNativeEvent(check, behavior, snapshots, failures);
+    }
+    return {
+      ...check,
+      mechanism: decision?.mechanism,
+      passed: failures.length === 0,
+      failures,
+    };
+  });
+
+  const behaviorResults = (plan?.behaviors || []).map((behavior) => {
+    const decision = mechanismByBehavior.get(behavior.id);
+    const matching = verifiedChecks.filter((check) =>
+      check.behaviorId === behavior.id);
+    const suppliedTargets = new Set(
+      matching.flatMap((check) =>
+        decision?.mechanism === 'native_component_variants'
+        || decision?.mechanism === 'existing_component_control'
+        || decision?.mechanism === 'code_component'
+          ? check.instanceNodeIds
+          : [check.triggerNodeId]),
+    );
+    const failures = matching.flatMap((check) => check.failures);
+    if (matching.length === 0) failures.push('no evidence was supplied');
+    if (suppliedTargets.size < behavior.expectedTargets) {
+      failures.push(
+        `verified ${suppliedTargets.size} of ${behavior.expectedTargets} expected targets`,
+      );
+    }
+    return {
+      behaviorId: behavior.id,
+      behaviorSignature: behavior.signature,
+      mechanism: decision?.mechanism,
+      expectedTargets: behavior.expectedTargets,
+      verifiedTargets: suppliedTargets.size,
+      passed: failures.length === 0,
+      failures: uniqueStrings(failures, 50),
+    };
+  });
+  const representativeBehaviorIds = behaviorResults
+    .filter((result) =>
+      verifiedChecks.some((check) =>
+        check.behaviorId === result.behaviorId && check.passed))
+    .map((result) => result.behaviorId);
+  const completed =
+    behaviorResults.length > 0
+    && behaviorResults.every((result) => result.passed);
+  return {
+    completed,
+    verificationLevel: completed
+      ? 'structurally_verified'
+      : 'unverified',
+    checks: verifiedChecks,
+    behaviors: behaviorResults,
+    representativeBehaviorIds,
+  };
+}
+
+export function summarizeFramerChanges(changes) {
+  const commands = String(changes || '')
+    .split(';')
+    .map((command) => command.trim())
+    .filter(Boolean)
+    .slice(0, 200)
+    .map((command) => {
+      const created = command.match(/^\+([A-Za-z0-9_]+)\s+([^\s]+)/);
+      if (created) {
+        return {
+          operation: 'create',
+          nodeType: created[1],
+          nodeId: created[2],
+          parentId: command.match(/\bparent="([^"]+)"/)?.[1],
+        };
+      }
+      const set = command.match(/^SET\s+([^\s]+)/i);
+      if (set) {
+        return {
+          operation: 'set',
+          nodeId: set[1],
+          eventActions: Array.from(
+            command.matchAll(
+              /\b(on[A-Za-z]+)\.\d+\.action="([A-Z_]+)"/g,
+            ),
+          ).map((match) => ({ event: match[1], action: match[2] })),
+        };
+      }
+      const variant = command.match(/^CREATE_VARIANT\s+([^\s]+)\s+from="([^"]+)"/i);
+      if (variant) {
+        return {
+          operation: 'create_variant',
+          nodeId: variant[1],
+          sourceNodeId: variant[2],
+        };
+      }
+      const operation = text(command.split(/\s+/)[0], 40).toLowerCase();
+      return { operation: operation || 'unknown' };
+    });
+  return {
+    changeHash: crypto
+      .createHash('sha256')
+      .update(String(changes || ''))
+      .digest('hex'),
+    commandCount: commands.length,
+    commands,
+  };
+}
+
+export function canonicalIdMappings(value) {
+  const mappings = {};
+  const visit = (current) => {
+    if (Array.isArray(current)) {
+      current.forEach(visit);
+      return;
+    }
+    if (!isRecord(current)) return;
+    if (isRecord(current.renamedIds)) {
+      for (const [temporaryId, canonicalId] of Object.entries(
+        current.renamedIds,
+      )) {
+        const safeTemporary = text(temporaryId, 200);
+        const safeCanonical = text(canonicalId, 200);
+        if (safeTemporary && safeCanonical) {
+          mappings[safeTemporary] = safeCanonical;
+        }
+      }
+    }
+    Object.values(current).forEach(visit);
+  };
+  visit(value);
+  return mappings;
+}