@qontinui/ui-bridge 0.3.0 → 0.3.1

package/dist/react/index.js

@@ -552,7 +552,9 @@ function generateDescription(input) {
     }
     parts.push(`"${name}"`);
   }
-  const typeWords = ELEMENT_ACTION_WORDS[input.elementType || ""] || [input.elementType || "element"];
+  const typeWords = ELEMENT_ACTION_WORDS[input.elementType || ""] || [
+    input.elementType || "element"
+  ];
   parts.push(typeWords[0]);
   if (input.inputType && input.inputType !== "text") {
     parts.push(`(${input.inputType})`);
@@ -773,12 +775,38 @@ var UIBridgeRegistry = class {
       getState: () => getElementState(element),
       getIdentifier: () => createElementIdentifier(element),
       registeredAt: Date.now(),
-      mounted: true
+      mounted: true,
+      category: options.category ?? "interactive",
+      contentMetadata: options.contentMetadata
     };
     this.elements.set(actualId, registered);
     this.emit("element:registered", { id: actualId, type, label: options.label });
     return registered;
   }
+  /**
+   * Register a content (non-interactive) element
+   */
+  registerContentElement(id, element, options) {
+    return this.registerElement(id, element, {
+      type: options.contentType,
+      label: options.label,
+      actions: [],
+      category: "content",
+      contentMetadata: options.contentMetadata
+    });
+  }
+  /**
+   * Get all content (non-interactive) elements
+   */
+  getAllContentElements() {
+    return Array.from(this.elements.values()).filter((el) => el.category === "content");
+  }
+  /**
+   * Get all interactive elements
+   */
+  getAllInteractiveElements() {
+    return Array.from(this.elements.values()).filter((el) => el.category !== "content");
+  }
   /**
    * Unregister an element
    */
@@ -875,7 +903,9 @@ var UIBridgeRegistry = class {
             scores.accessibility = result.similarity;
             if (result.similarity > maxScore) {
               maxScore = result.similarity;
-              matchReasons.push(`accessible name similarity: ${(result.similarity * 100).toFixed(0)}%`);
+              matchReasons.push(
+                `accessible name similarity: ${(result.similarity * 100).toFixed(0)}%`
+              );
             }
           }
         }
@@ -1471,8 +1501,56 @@ var UIBridgeRegistry = class {
         identifier: el.getIdentifier(),
         state: el.getState(),
         actions: el.actions,
-        customActions: el.customActions ? Object.keys(el.customActions) : void 0
+        customActions: el.customActions ? Object.keys(el.customActions) : void 0,
+        category: el.category,
+        contentMetadata: el.contentMetadata
+      })),
+      components: this.getAllComponents().map((comp) => ({
+        id: comp.id,
+        name: comp.name,
+        description: comp.description,
+        actions: comp.actions.map((a) => a.id),
+        elementIds: comp.elementIds
       })),
+      workflows: this.getAllWorkflows().map((wf) => ({
+        id: wf.id,
+        name: wf.name,
+        description: wf.description,
+        stepCount: wf.steps.length
+      }))
+    };
+  }
+  /**
+   * Create a snapshot asynchronously, processing elements in batches to avoid
+   * blocking the main thread. This prevents "Page Unresponsive" dialogs when
+   * there are many registered elements (200-500+), since getState() and
+   * getIdentifier() force layout/style recalculation for each element.
+   */
+  async createSnapshotAsync(batchSize = 50) {
+    const allElements = this.getAllElements();
+    const elementSnapshots = [];
+    for (let i = 0; i < allElements.length; i += batchSize) {
+      const batch = allElements.slice(i, i + batchSize);
+      for (const el of batch) {
+        elementSnapshots.push({
+          id: el.id,
+          type: el.type,
+          label: el.label,
+          identifier: el.getIdentifier(),
+          state: el.getState(),
+          actions: el.actions,
+          customActions: el.customActions ? Object.keys(el.customActions) : void 0,
+          category: el.category,
+          contentMetadata: el.contentMetadata
+        });
+      }
+      if (i + batchSize < allElements.length) {
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      }
+    }
+    return {
+      timestamp: Date.now(),
+      elements: elementSnapshots,
       components: this.getAllComponents().map((comp) => ({
         id: comp.id,
         name: comp.name,
@@ -1997,6 +2075,10 @@ function getElementState2(element) {
       pointerEvents: style.pointerEvents
     }
   };
+  const rawText = element.textContent?.trim();
+  if (rawText) {
+    state.textContent = rawText.replace(/\s+/g, " ").slice(0, 500);
+  }
   if (element instanceof HTMLInputElement) {
     state.value = element.value;
     if (element.type === "checkbox" || element.type === "radio") {
@@ -2038,9 +2120,25 @@ function createMouseEvent(type, element, options) {
     clientY: rect.top + y
   });
 }
+function elementFromPointSafe(x, y) {
+  if (typeof document.elementFromPoint === "function") {
+    return document.elementFromPoint(x, y);
+  }
+  return null;
+}
+function createMouseEventAt(type, clientX, clientY) {
+  return new MouseEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    button: 0,
+    clientX,
+    clientY
+  });
+}
 var DefaultActionExecutor = class {
-  constructor(registry) {
+  constructor(registry, consoleCapture) {
     this.registry = registry;
+    this.consoleCapture = consoleCapture;
   }
   /**
    * Execute an action on an element
@@ -2077,11 +2175,19 @@ var DefaultActionExecutor = class {
           };
         }
       }
+      const actionStartTime = Date.now();
       const result = await this.performAction(element, request.action, request.params);
+      let consoleErrors;
+      if (this.consoleCapture) {
+        await sleep(50);
+        const errors = this.consoleCapture.getConsoleSince(actionStartTime);
+        if (errors.length > 0) consoleErrors = errors;
+      }
       return {
         success: true,
         elementState: getElementState2(element),
         result,
+        consoleErrors,
         durationMs: performance.now() - startTime,
         timestamp: Date.now(),
         requestId: request.requestId,
@@ -2173,47 +2279,76 @@ var DefaultActionExecutor = class {
       const rootEl = document.querySelector(options.root);
       if (rootEl) root = rootEl;
     }
-    const interactiveSelectors = [
-      "a[href]",
-      "button",
-      "input",
-      "select",
-      "textarea",
-      "[onclick]",
-      '[role="button"]',
-      '[role="link"]',
-      '[role="checkbox"]',
-      '[role="radio"]',
-      '[role="menuitem"]',
-      '[role="tab"]',
-      '[role="switch"]',
-      '[tabindex]:not([tabindex="-1"])',
-      '[contenteditable="true"]',
-      "[data-ui-id]",
-      "[data-testid]"
-    ];
-    const selector = options?.selector || interactiveSelectors.join(", ");
-    const foundElements = root.querySelectorAll(selector);
-    for (const el of foundElements) {
-      if (options?.limit && elements.length >= options.limit) break;
-      const state = getElementState2(el);
-      if (!options?.includeHidden && !state.visible) continue;
-      if (options?.types) {
-        const type = this.inferElementType(el);
-        if (!options.types.includes(type)) continue;
-      }
-      const registered = this.registry.findByDOMElement(el);
-      elements.push({
-        id: registered?.id || this.getElementId(el),
-        type: registered?.type || this.inferElementType(el),
-        label: registered?.label || this.getElementLabel(el),
-        tagName: el.tagName.toLowerCase(),
-        role: el.getAttribute("role") || void 0,
-        accessibleName: this.getAccessibleName(el),
-        actions: registered?.actions || this.inferActions(el),
-        state,
-        registered: !!registered
-      });
+    if (!options?.contentOnly) {
+      const interactiveSelectors = [
+        "a[href]",
+        "button",
+        "input",
+        "select",
+        "textarea",
+        "[onclick]",
+        '[role="button"]',
+        '[role="link"]',
+        '[role="checkbox"]',
+        '[role="radio"]',
+        '[role="menuitem"]',
+        '[role="tab"]',
+        '[role="switch"]',
+        '[tabindex]:not([tabindex="-1"])',
+        '[contenteditable="true"]',
+        "[data-ui-element]",
+        "[data-ui-id]",
+        "[data-testid]"
+      ];
+      const selector = options?.selector || interactiveSelectors.join(", ");
+      const foundElements = root.querySelectorAll(selector);
+      for (const el of foundElements) {
+        if (options?.limit && elements.length >= options.limit) break;
+        const state = getElementState2(el);
+        if (!options?.includeHidden && !state.visible) continue;
+        if (options?.types) {
+          const type = this.inferElementType(el);
+          if (!options.types.includes(type)) continue;
+        }
+        const registered = this.registry.findByDOMElement(el);
+        elements.push({
+          id: registered?.id || this.getElementId(el),
+          type: registered?.type || this.inferElementType(el),
+          label: registered?.label || this.getElementLabel(el),
+          tagName: el.tagName.toLowerCase(),
+          role: el.getAttribute("role") || void 0,
+          accessibleName: this.getAccessibleName(el),
+          actions: registered?.actions || this.inferActions(el),
+          state,
+          registered: !!registered,
+          category: registered?.category || "interactive",
+          contentMetadata: registered?.contentMetadata
+        });
+      }
+    }
+    if (options?.includeContent || options?.contentOnly) {
+      const contentElements = this.registry.getAllContentElements();
+      for (const el of contentElements) {
+        if (options?.limit && elements.length >= options.limit) break;
+        const state = el.getState();
+        if (!options?.includeHidden && !state.visible) continue;
+        if (options?.contentRole && el.contentMetadata?.contentRole !== options.contentRole) {
+          continue;
+        }
+        elements.push({
+          id: el.id,
+          type: el.type,
+          label: el.label,
+          tagName: el.element.tagName.toLowerCase(),
+          role: el.element.getAttribute("role") || void 0,
+          accessibleName: el.label || state.textContent?.trim(),
+          actions: [],
+          state,
+          registered: true,
+          category: "content",
+          contentMetadata: el.contentMetadata
+        });
+      }
     }
     return {
       elements,
@@ -2243,7 +2378,9 @@ var DefaultActionExecutor = class {
         type: el.type,
         label: el.label,
         actions: [...el.actions, ...el.customActions ? Object.keys(el.customActions) : []],
-        state: el.getState()
+        state: el.getState(),
+        category: el.category,
+        contentMetadata: el.contentMetadata
       })),
       components: components.map((comp) => ({
         id: comp.id,
@@ -2327,6 +2464,14 @@ var DefaultActionExecutor = class {
         return this.performCheck(element, false);
       case "toggle":
         return this.performToggle(element);
+      case "drag":
+        return this.performDrag(element, params);
+      case "setValue":
+        return this.performSetValue(element, params);
+      case "submit":
+        return this.performSubmit(element);
+      case "reset":
+        return this.performReset(element);
       default: {
         const registered = this.registry.findByDOMElement(element);
         if (registered?.customActions?.[action]) {
@@ -2356,15 +2501,26 @@ var DefaultActionExecutor = class {
     if (!(element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement)) {
       throw new Error("Type action requires an input or textarea element");
     }
+    const proto = element instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+    const nativeSetter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
     element.focus();
     if (options?.clear) {
-      element.value = "";
+      if (nativeSetter) {
+        nativeSetter.call(element, "");
+      } else {
+        element.value = "";
+      }
       element.dispatchEvent(new Event("input", { bubbles: true }));
     }
     const text = options?.text || "";
     const delay = options?.delay || 0;
     for (const char of text) {
-      element.value += char;
+      const current = element.value;
+      if (nativeSetter) {
+        nativeSetter.call(element, current + char);
+      } else {
+        element.value = current + char;
+      }
       if (options?.triggerEvents !== false) {
         element.dispatchEvent(new Event("input", { bubbles: true }));
       }
@@ -2378,7 +2534,13 @@ var DefaultActionExecutor = class {
   }
   performClear(element) {
     if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) {
-      element.value = "";
+      const proto = element instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+      const nativeSetter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
+      if (nativeSetter) {
+        nativeSetter.call(element, "");
+      } else {
+        element.value = "";
+      }
       element.dispatchEvent(new Event("input", { bubbles: true }));
       element.dispatchEvent(new Event("change", { bubbles: true }));
     }
@@ -2460,6 +2622,150 @@ var DefaultActionExecutor = class {
       element.dispatchEvent(new Event("change", { bubbles: true }));
     }
   }
+  performSetValue(element, params) {
+    const value = params?.value;
+    if (value === void 0) {
+      throw new Error('setValue requires a "value" parameter');
+    }
+    if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) {
+      const nativeSetter = Object.getOwnPropertyDescriptor(
+        element instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype,
+        "value"
+      )?.set;
+      if (nativeSetter) {
+        nativeSetter.call(element, value);
+      } else {
+        element.value = value;
+      }
+      element.dispatchEvent(new Event("input", { bubbles: true }));
+      element.dispatchEvent(new Event("change", { bubbles: true }));
+    } else if (element instanceof HTMLSelectElement) {
+      element.value = value;
+      element.dispatchEvent(new Event("change", { bubbles: true }));
+    }
+  }
+  performSubmit(element) {
+    const form = element instanceof HTMLFormElement ? element : element.closest("form");
+    if (form) {
+      const submitEvent = new Event("submit", { bubbles: true, cancelable: true });
+      if (form.dispatchEvent(submitEvent)) {
+        form.requestSubmit();
+      }
+    } else {
+      throw new Error("No form found for submit action");
+    }
+  }
+  performReset(element) {
+    const form = element instanceof HTMLFormElement ? element : element.closest("form");
+    if (form) {
+      form.reset();
+      form.dispatchEvent(new Event("reset", { bubbles: true }));
+    } else {
+      throw new Error("No form found for reset action");
+    }
+  }
+  /**
+   * Perform a drag operation by dispatching a sequence of mouse events.
+   *
+   * Follows the same composite pattern as the qontinui core library:
+   * mousedown on source → wait → mousemove × N along path → mouseup on target.
+   *
+   * Optionally dispatches HTML5 drag events (dragstart/dragover/drop/dragend)
+   * for apps that use the HTML5 Drag and Drop API instead of mouse events.
+   */
+  async performDrag(sourceElement, options) {
+    const sourceRect = sourceElement.getBoundingClientRect();
+    const sourceX = sourceRect.left + (options?.sourceOffset?.x ?? sourceRect.width / 2);
+    const sourceY = sourceRect.top + (options?.sourceOffset?.y ?? sourceRect.height / 2);
+    let targetX;
+    let targetY;
+    if (options?.targetPosition) {
+      targetX = options.targetPosition.x;
+      targetY = options.targetPosition.y;
+    } else if (options?.target) {
+      const targetElement = this.resolveTargetElement(options.target);
+      if (!targetElement) {
+        throw new Error(`Drag target element not found: ${JSON.stringify(options.target)}`);
+      }
+      const targetRect = targetElement.getBoundingClientRect();
+      targetX = targetRect.left + (options?.targetOffset?.x ?? targetRect.width / 2);
+      targetY = targetRect.top + (options?.targetOffset?.y ?? targetRect.height / 2);
+    } else {
+      throw new Error("Drag requires either target or targetPosition");
+    }
+    const steps = options?.steps ?? 10;
+    const holdDelay = options?.holdDelay ?? 100;
+    const releaseDelay = options?.releaseDelay ?? 50;
+    sourceElement.dispatchEvent(createMouseEventAt("mousedown", sourceX, sourceY));
+    const canHTML5 = options?.html5 && typeof DragEvent !== "undefined";
+    if (canHTML5) {
+      sourceElement.dispatchEvent(
+        new DragEvent("dragstart", {
+          bubbles: true,
+          cancelable: true,
+          clientX: sourceX,
+          clientY: sourceY
+        })
+      );
+    }
+    if (holdDelay > 0) {
+      await sleep(holdDelay);
+    }
+    for (let i = 1; i <= steps; i++) {
+      const progress = i / steps;
+      const currentX = sourceX + (targetX - sourceX) * progress;
+      const currentY = sourceY + (targetY - sourceY) * progress;
+      const dispatchTarget = elementFromPointSafe(currentX, currentY) || sourceElement;
+      dispatchTarget.dispatchEvent(createMouseEventAt("mousemove", currentX, currentY));
+      if (canHTML5) {
+        dispatchTarget.dispatchEvent(
+          new DragEvent("dragover", {
+            bubbles: true,
+            cancelable: true,
+            clientX: currentX,
+            clientY: currentY
+          })
+        );
+      }
+    }
+    const dropTarget = elementFromPointSafe(targetX, targetY) || sourceElement;
+    dropTarget.dispatchEvent(createMouseEventAt("mouseup", targetX, targetY));
+    if (canHTML5) {
+      dropTarget.dispatchEvent(
+        new DragEvent("drop", {
+          bubbles: true,
+          cancelable: true,
+          clientX: targetX,
+          clientY: targetY
+        })
+      );
+      sourceElement.dispatchEvent(
+        new DragEvent("dragend", {
+          bubbles: true,
+          cancelable: true,
+          clientX: targetX,
+          clientY: targetY
+        })
+      );
+    }
+    if (releaseDelay > 0) {
+      await sleep(releaseDelay);
+    }
+  }
+  /**
+   * Resolve a drag target element from a target descriptor.
+   */
+  resolveTargetElement(target) {
+    if (target.elementId) {
+      const registered = this.registry.getElement(target.elementId);
+      if (registered?.element) return registered.element;
+      return findElementByIdentifier(target.elementId);
+    }
+    if (target.selector) {
+      return document.querySelector(target.selector);
+    }
+    return null;
+  }
   getElementId(element) {
     return element.getAttribute("data-ui-id") || element.getAttribute("data-testid") || element.id || `${element.tagName.toLowerCase()}-${Math.random().toString(36).substr(2, 8)}`;
   }
@@ -2555,8 +2861,442 @@ var DefaultActionExecutor = class {
     }
   }
 };
-function createActionExecutor(registry) {
-  return new DefaultActionExecutor(registry);
+function createActionExecutor(registry, consoleCapture) {
+  return new DefaultActionExecutor(registry, consoleCapture);
+}
+
+// src/specs/types.ts
+var SPEC_CONFIG_VERSION = "1.0.0";
+var VALID_ASSERTION_TYPES = [
+  "visible",
+  "hidden",
+  "enabled",
+  "disabled",
+  "focused",
+  "checked",
+  "unchecked",
+  "hasText",
+  "containsText",
+  "hasValue",
+  "hasClass",
+  "exists",
+  "notExists",
+  "count",
+  "attribute",
+  "cssProperty"
+];
+var VALID_SPEC_CATEGORIES = [
+  "element-presence",
+  "accessibility",
+  "form-validation",
+  "state-consistency",
+  "modal-dialog",
+  "navigation",
+  "cross-page-consistency",
+  "custom"
+];
+var VALID_SPEC_SEVERITIES = [
+  "critical",
+  "warning",
+  "info"
+];
+var VALID_SPEC_SOURCES = [
+  "auto",
+  "manual",
+  "ai-generated"
+];
+
+// src/specs/validator.ts
+function isValidAssertionType(value) {
+  return typeof value === "string" && VALID_ASSERTION_TYPES.includes(value);
+}
+function isValidSpecCategory(value) {
+  return typeof value === "string" && VALID_SPEC_CATEGORIES.includes(value);
+}
+function isValidSpecSeverity(value) {
+  return typeof value === "string" && VALID_SPEC_SEVERITIES.includes(value);
+}
+function isValidSpecSource(value) {
+  return typeof value === "string" && VALID_SPEC_SOURCES.includes(value);
+}
+function validateSpecAssertion(data, path = "assertion") {
+  const errors = [];
+  if (!data || typeof data !== "object") {
+    errors.push({ path, message: "must be an object" });
+    return errors;
+  }
+  const obj = data;
+  if (typeof obj.id !== "string" || obj.id.length === 0) {
+    errors.push({ path: `${path}.id`, message: "must be a non-empty string" });
+  }
+  if (typeof obj.description !== "string") {
+    errors.push({ path: `${path}.description`, message: "must be a string" });
+  }
+  if (!isValidSpecCategory(obj.category)) {
+    errors.push({
+      path: `${path}.category`,
+      message: `must be one of: ${VALID_SPEC_CATEGORIES.join(", ")}`
+    });
+  }
+  if (!isValidSpecSeverity(obj.severity)) {
+    errors.push({
+      path: `${path}.severity`,
+      message: `must be one of: ${VALID_SPEC_SEVERITIES.join(", ")}`
+    });
+  }
+  if (!obj.target || typeof obj.target !== "object") {
+    errors.push({ path: `${path}.target`, message: "must be an object" });
+  } else {
+    const target = obj.target;
+    if (target.type === "elementId") {
+      if (typeof target.elementId !== "string" || target.elementId.length === 0) {
+        errors.push({ path: `${path}.target.elementId`, message: "must be a non-empty string" });
+      }
+    } else if (target.type === "search") {
+      if (!target.criteria || typeof target.criteria !== "object") {
+        errors.push({ path: `${path}.target.criteria`, message: "must be an object" });
+      }
+    } else {
+      errors.push({ path: `${path}.target.type`, message: 'must be "elementId" or "search"' });
+    }
+  }
+  if (!isValidAssertionType(obj.assertionType)) {
+    errors.push({
+      path: `${path}.assertionType`,
+      message: `must be one of: ${VALID_ASSERTION_TYPES.join(", ")}`
+    });
+  }
+  if (!isValidSpecSource(obj.source)) {
+    errors.push({
+      path: `${path}.source`,
+      message: `must be one of: ${VALID_SPEC_SOURCES.join(", ")}`
+    });
+  }
+  if (typeof obj.reviewed !== "boolean") {
+    errors.push({ path: `${path}.reviewed`, message: "must be a boolean" });
+  }
+  if (typeof obj.enabled !== "boolean") {
+    errors.push({ path: `${path}.enabled`, message: "must be a boolean" });
+  }
+  if (obj.timeout !== void 0 && (typeof obj.timeout !== "number" || obj.timeout < 0)) {
+    errors.push({ path: `${path}.timeout`, message: "must be a non-negative number" });
+  }
+  return errors;
+}
+function validateSpecGroup(data, path = "group") {
+  const errors = [];
+  if (!data || typeof data !== "object") {
+    errors.push({ path, message: "must be an object" });
+    return errors;
+  }
+  const obj = data;
+  if (typeof obj.id !== "string" || obj.id.length === 0) {
+    errors.push({ path: `${path}.id`, message: "must be a non-empty string" });
+  }
+  if (typeof obj.name !== "string") {
+    errors.push({ path: `${path}.name`, message: "must be a string" });
+  }
+  if (typeof obj.description !== "string") {
+    errors.push({ path: `${path}.description`, message: "must be a string" });
+  }
+  if (!isValidSpecCategory(obj.category)) {
+    errors.push({
+      path: `${path}.category`,
+      message: `must be one of: ${VALID_SPEC_CATEGORIES.join(", ")}`
+    });
+  }
+  if (!isValidSpecSource(obj.source)) {
+    errors.push({
+      path: `${path}.source`,
+      message: `must be one of: ${VALID_SPEC_SOURCES.join(", ")}`
+    });
+  }
+  if (!Array.isArray(obj.assertions)) {
+    errors.push({ path: `${path}.assertions`, message: "must be an array" });
+  } else {
+    for (let i = 0; i < obj.assertions.length; i++) {
+      errors.push(...validateSpecAssertion(obj.assertions[i], `${path}.assertions[${i}]`));
+    }
+  }
+  return errors;
+}
+function validateSpecConfig(data) {
+  const errors = [];
+  if (!data || typeof data !== "object") {
+    return { valid: false, errors: [{ path: "", message: "must be an object" }] };
+  }
+  const obj = data;
+  if (obj.version !== SPEC_CONFIG_VERSION) {
+    errors.push({ path: "version", message: `must be "${SPEC_CONFIG_VERSION}"` });
+  }
+  if (obj.description !== void 0 && typeof obj.description !== "string") {
+    errors.push({ path: "description", message: "must be a string if provided" });
+  }
+  if (!Array.isArray(obj.groups)) {
+    errors.push({ path: "groups", message: "must be an array" });
+  } else {
+    for (let i = 0; i < obj.groups.length; i++) {
+      errors.push(...validateSpecGroup(obj.groups[i], `groups[${i}]`));
+    }
+  }
+  if (obj.assertions !== void 0) {
+    if (!Array.isArray(obj.assertions)) {
+      errors.push({ path: "assertions", message: "must be an array if provided" });
+    } else {
+      for (let i = 0; i < obj.assertions.length; i++) {
+        errors.push(...validateSpecAssertion(obj.assertions[i], `assertions[${i}]`));
+      }
+    }
+  }
+  if (obj.metadata !== void 0 && (typeof obj.metadata !== "object" || obj.metadata === null)) {
+    errors.push({ path: "metadata", message: "must be an object if provided" });
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+// src/specs/store.ts
+var SpecStore = class {
+  constructor() {
+    this.configs = /* @__PURE__ */ new Map();
+    this.listeners = /* @__PURE__ */ new Set();
+  }
+  // ---------------------------------------------------------------------------
+  // CRUD — Config Level
+  // ---------------------------------------------------------------------------
+  load(specId, config) {
+    this.configs.set(specId, config);
+    this.emit({ type: "spec:loaded", specId, timestamp: Date.now() });
+  }
+  unload(specId) {
+    const existed = this.configs.delete(specId);
+    if (existed) {
+      this.emit({ type: "spec:unloaded", specId, timestamp: Date.now() });
+    }
+    return existed;
+  }
+  get(specId) {
+    return this.configs.get(specId);
+  }
+  has(specId) {
+    return this.configs.has(specId);
+  }
+  getIds() {
+    return Array.from(this.configs.keys());
+  }
+  getAll() {
+    return new Map(this.configs);
+  }
+  get count() {
+    return this.configs.size;
+  }
+  clear() {
+    this.configs.clear();
+    this.emit({ type: "spec:cleared", timestamp: Date.now() });
+  }
+  // ---------------------------------------------------------------------------
+  // CRUD — Group Level
+  // ---------------------------------------------------------------------------
+  addGroup(specId, group) {
+    const config = this.configs.get(specId);
+    if (!config) return false;
+    config.groups.push(group);
+    this.emit({ type: "spec:group-added", specId, groupId: group.id, timestamp: Date.now() });
+    return true;
+  }
+  removeGroup(specId, groupId) {
+    const config = this.configs.get(specId);
+    if (!config) return false;
+    const idx = config.groups.findIndex((g) => g.id === groupId);
+    if (idx === -1) return false;
+    config.groups.splice(idx, 1);
+    this.emit({ type: "spec:group-removed", specId, groupId, timestamp: Date.now() });
+    return true;
+  }
+  getGroup(specId, groupId) {
+    const config = this.configs.get(specId);
+    if (!config) return void 0;
+    return config.groups.find((g) => g.id === groupId);
+  }
+  // ---------------------------------------------------------------------------
+  // CRUD — Assertion Level
+  // ---------------------------------------------------------------------------
+  addAssertion(specId, groupId, assertion) {
+    const config = this.configs.get(specId);
+    if (!config) return false;
+    if (groupId) {
+      const group = config.groups.find((g) => g.id === groupId);
+      if (!group) return false;
+      group.assertions.push(assertion);
+    } else {
+      if (!config.assertions) config.assertions = [];
+      config.assertions.push(assertion);
+    }
+    this.emit({
+      type: "spec:assertion-added",
+      specId,
+      groupId: groupId ?? void 0,
+      assertionId: assertion.id,
+      timestamp: Date.now()
+    });
+    return true;
+  }
+  removeAssertion(specId, groupId, assertionId) {
+    const config = this.configs.get(specId);
+    if (!config) return false;
+    let removed = false;
+    if (groupId) {
+      const group = config.groups.find((g) => g.id === groupId);
+      if (group) {
+        const idx = group.assertions.findIndex((a) => a.id === assertionId);
+        if (idx !== -1) {
+          group.assertions.splice(idx, 1);
+          removed = true;
+        }
+      }
+    } else if (config.assertions) {
+      const idx = config.assertions.findIndex((a) => a.id === assertionId);
+      if (idx !== -1) {
+        config.assertions.splice(idx, 1);
+        removed = true;
+      }
+    }
+    if (removed) {
+      this.emit({
+        type: "spec:assertion-removed",
+        specId,
+        groupId: groupId ?? void 0,
+        assertionId,
+        timestamp: Date.now()
+      });
+    }
+    return removed;
+  }
+  toggleAssertion(specId, groupId, assertionId) {
+    const assertion = this.findAssertion(specId, groupId, assertionId);
+    if (!assertion) return false;
+    assertion.enabled = !assertion.enabled;
+    this.emit({ type: "spec:updated", specId, timestamp: Date.now() });
+    return true;
+  }
+  markReviewed(specId, groupId, assertionId) {
+    const assertion = this.findAssertion(specId, groupId, assertionId);
+    if (!assertion) return false;
+    assertion.reviewed = !assertion.reviewed;
+    this.emit({ type: "spec:updated", specId, timestamp: Date.now() });
+    return true;
+  }
+  // ---------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------
+  getAllAssertions() {
+    const result = [];
+    for (const config of this.configs.values()) {
+      for (const group of config.groups) {
+        result.push(...group.assertions);
+      }
+      if (config.assertions) {
+        result.push(...config.assertions);
+      }
+    }
+    return result;
+  }
+  filterAssertions(opts) {
+    return this.getAllAssertions().filter((a) => {
+      if (opts.categories && !opts.categories.includes(a.category)) return false;
+      if (opts.severities && !opts.severities.includes(a.severity)) return false;
+      if (opts.enabledOnly && !a.enabled) return false;
+      if (opts.reviewedOnly && !a.reviewed) return false;
+      return true;
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Coverage
+  // ---------------------------------------------------------------------------
+  getCoverage(allElementIds) {
+    const specifiedIdSet = /* @__PURE__ */ new Set();
+    for (const assertion of this.getAllAssertions()) {
+      if (assertion.target.type === "elementId") {
+        specifiedIdSet.add(assertion.target.elementId);
+      }
+    }
+    const specifiedIds = [];
+    const unspecifiedIds = [];
+    for (const id of allElementIds) {
+      if (specifiedIdSet.has(id)) {
+        specifiedIds.push(id);
+      } else {
+        unspecifiedIds.push(id);
+      }
+    }
+    const total = allElementIds.length;
+    return {
+      totalElements: total,
+      specifiedElements: specifiedIds.length,
+      coveragePercent: total > 0 ? specifiedIds.length / total * 100 : 0,
+      specifiedIds,
+      unspecifiedIds,
+      timestamp: Date.now()
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Import / Export
+  // ---------------------------------------------------------------------------
+  importConfig(specId, config) {
+    const result = validateSpecConfig(config);
+    if (!result.valid) return false;
+    this.configs.set(specId, config);
+    this.emit({ type: "spec:loaded", specId, timestamp: Date.now() });
+    return true;
+  }
+  exportConfig(specId) {
+    const config = this.configs.get(specId);
+    if (!config) return void 0;
+    return {
+      ...config,
+      version: SPEC_CONFIG_VERSION,
+      metadata: {
+        ...config.metadata,
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Events
+  // ---------------------------------------------------------------------------
+  on(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  emit(event) {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+      }
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Private Helpers
+  // ---------------------------------------------------------------------------
+  findAssertion(specId, groupId, assertionId) {
+    const config = this.configs.get(specId);
+    if (!config) return void 0;
+    if (groupId) {
+      const group = config.groups.find((g) => g.id === groupId);
+      if (!group) return void 0;
+      return group.assertions.find((a) => a.id === assertionId);
+    }
+    return config.assertions?.find((a) => a.id === assertionId);
+  }
+};
+var globalStore = null;
+function getGlobalSpecStore() {
+  if (!globalStore) {
+    globalStore = new SpecStore();
+  }
+  return globalStore;
 }
 
 // src/control/workflow-engine.ts
@@ -3588,34 +4328,690 @@ var MetricsCollector = class {
 function createMetricsCollector(options) {
   return new MetricsCollector(options);
 }
-var UIBridgeContext = react.createContext(null);
-function UIBridgeProvider({
-  children,
-  features = {},
-  config = {},
-  onEvent
-}) {
-  const registryRef = react.useRef(null);
-  const renderLogRef = react.useRef(null);
-  const metricsRef = react.useRef(null);
-  const wsClientRef = react.useRef(null);
-  const [wsConnectionState, setWsConnectionState] = react.useState("disconnected");
-  if (!registryRef.current) {
-    registryRef.current = new UIBridgeRegistry({
-      verbose: config.verbose,
-      onEvent
-    });
-    setGlobalRegistry(registryRef.current);
-    if (features.renderLog) {
-      renderLogRef.current = createRenderLogManager({
-        maxEntries: config.maxLogEntries
-      });
+
+// src/debug/browser-capture-types.ts
+var DEFAULT_CAPTURE_CONFIG = {
+  console: true,
+  network: true,
+  navigation: true,
+  longTasks: true,
+  longAnimationFrames: true,
+  resourceErrors: true,
+  wsDisconnections: true,
+  hmr: true,
+  webVitals: false,
+  memory: false,
+  memoryIntervalMs: 3e4,
+  maxEntries: 200
+};
+
+// src/debug/captures/console.ts
+function argsToMessage(args) {
+  return args.map((a) => {
+    if (a instanceof Error) return a.message;
+    if (typeof a === "string") return a;
+    try {
+      return JSON.stringify(a);
+    } catch {
+      return String(a);
     }
-    if (features.debug) {
-      metricsRef.current = createMetricsCollector();
+  }).join(" ");
+}
+function extractStack(args) {
+  const err = args.find((a) => a instanceof Error);
+  return err?.stack;
+}
+function makeEvent(level, message, stack) {
+  return {
+    type: "console",
+    timestamp: Date.now(),
+    url: typeof window !== "undefined" ? window.location.href : "",
+    level,
+    message,
+    stack
+  };
+}
+function installConsoleCapture(emit) {
+  const originalError = console.error;
+  const originalWarn = console.warn;
+  console.error = (...args) => {
+    emit(makeEvent("error", argsToMessage(args), extractStack(args)));
+    originalError.apply(console, args);
+  };
+  console.warn = (...args) => {
+    emit(makeEvent("warn", argsToMessage(args), extractStack(args)));
+    originalWarn.apply(console, args);
+  };
+  const rejectionHandler = (event) => {
+    const reason = event.reason;
+    const message = reason instanceof Error ? reason.message : String(reason ?? "Unhandled rejection");
+    const stack = reason instanceof Error ? reason.stack : void 0;
+    emit(makeEvent("unhandledrejection", message, stack));
+  };
+  if (typeof window !== "undefined") {
+    window.addEventListener("unhandledrejection", rejectionHandler);
+  }
+  return () => {
+    console.error = originalError;
+    console.warn = originalWarn;
+    if (typeof window !== "undefined") {
+      window.removeEventListener("unhandledrejection", rejectionHandler);
     }
-    if (config.websocket) {
-      const wsPort = config.websocketPort || config.serverPort || 9876;
+  };
+}
+
+// src/debug/captures/network.ts
+var DEFAULT_IGNORE = ["/api/dev-debug/", "/api/ui-bridge/", "localhost:9876"];
+function installNetworkCapture(emit, options) {
+  if (typeof window === "undefined" || typeof window.fetch !== "function") {
+    return () => {
+    };
+  }
+  const originalFetch = window.fetch;
+  const ignorePatterns = options?.ignorePatterns ?? DEFAULT_IGNORE;
+  function shouldIgnore(url) {
+    return ignorePatterns.some((p) => url.includes(p));
+  }
+  function getMethod(input, init) {
+    if (init?.method) return init.method.toUpperCase();
+    if (input instanceof Request) return input.method.toUpperCase();
+    return "GET";
+  }
+  function getUrl(input) {
+    if (typeof input === "string") return input;
+    if (input instanceof URL) return input.href;
+    if (input instanceof Request) return input.url;
+    return String(input);
+  }
+  window.fetch = async function patchedFetch(input, init) {
+    const requestUrl = getUrl(input);
+    if (shouldIgnore(requestUrl)) {
+      return originalFetch.call(window, input, init);
+    }
+    const method = getMethod(input, init);
+    const start = performance.now();
+    try {
+      const response = await originalFetch.call(window, input, init);
+      const durationMs = Math.round(performance.now() - start);
+      if (response.status >= 400) {
+        const event = {
+          type: "network",
+          timestamp: Date.now(),
+          url: typeof window !== "undefined" ? window.location.href : "",
+          method,
+          requestUrl,
+          status: response.status,
+          statusText: response.statusText,
+          durationMs,
+          kind: "http-error"
+        };
+        emit(event);
+      }
+      return response;
+    } catch (err) {
+      const durationMs = Math.round(performance.now() - start);
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      let kind = "network-error";
+      if (err instanceof DOMException && err.name === "AbortError") {
+        kind = "abort";
+      } else if (errorMessage.includes("CORS") || errorMessage.includes("cross-origin")) {
+        kind = "cors";
+      } else if (errorMessage.includes("timeout") || errorMessage.includes("timed out")) {
+        kind = "timeout";
+      }
+      const event = {
+        type: "network",
+        timestamp: Date.now(),
+        url: typeof window !== "undefined" ? window.location.href : "",
+        method,
+        requestUrl,
+        durationMs,
+        kind,
+        errorMessage
+      };
+      emit(event);
+      throw err;
+    }
+  };
+  return () => {
+    window.fetch = originalFetch;
+  };
+}
+
+// src/debug/captures/navigation.ts
+function installNavigationCapture(emit) {
+  if (typeof window === "undefined" || typeof history === "undefined") {
+    return () => {
+    };
+  }
+  let lastUrl = window.location.href;
+  function emitNav(to, trigger) {
+    const from = lastUrl;
+    lastUrl = to;
+    if (from === to) return;
+    emit({
+      type: "navigation",
+      timestamp: Date.now(),
+      url: to,
+      from,
+      to,
+      trigger
+    });
+  }
+  const originalPushState = history.pushState;
+  const originalReplaceState = history.replaceState;
+  history.pushState = function(...args) {
+    originalPushState.apply(this, args);
+    emitNav(window.location.href, "pushState");
+  };
+  history.replaceState = function(...args) {
+    originalReplaceState.apply(this, args);
+    emitNav(window.location.href, "replaceState");
+  };
+  const popstateHandler = () => {
+    emitNav(window.location.href, "popstate");
+  };
+  window.addEventListener("popstate", popstateHandler);
+  return () => {
+    history.pushState = originalPushState;
+    history.replaceState = originalReplaceState;
+    window.removeEventListener("popstate", popstateHandler);
+  };
+}
+
+// src/debug/captures/long-tasks.ts
+function installLongTaskCapture(emit) {
+  if (typeof window === "undefined" || typeof PerformanceObserver === "undefined") {
+    return () => {
+    };
+  }
+  try {
+    const observer = new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        emit({
+          type: "long-task",
+          timestamp: Date.now(),
+          url: window.location.href,
+          durationMs: Math.round(entry.duration)
+        });
+      }
+    });
+    observer.observe({ type: "longtask", buffered: true });
+    return () => {
+      observer.disconnect();
+    };
+  } catch {
+    return () => {
+    };
+  }
+}
+
+// src/debug/captures/resource-errors.ts
+var TRACKED_TAGS = /* @__PURE__ */ new Set(["IMG", "SCRIPT", "LINK"]);
+function installResourceErrorCapture(emit) {
+  if (typeof window === "undefined") {
+    return () => {
+    };
+  }
+  const handler = (event) => {
+    const target = event.target;
+    if (!target || !target.tagName) return;
+    if (!TRACKED_TAGS.has(target.tagName)) return;
+    const resourceUrl = target.src || target.src || target.href || "";
+    if (!resourceUrl) return;
+    emit({
+      type: "resource-error",
+      timestamp: Date.now(),
+      url: window.location.href,
+      resourceUrl,
+      tagName: target.tagName
+    });
+  };
+  window.addEventListener("error", handler, true);
+  return () => {
+    window.removeEventListener("error", handler, true);
+  };
+}
+
+// src/debug/captures/web-vitals.ts
+function installWebVitalsCapture(emit) {
+  if (typeof window === "undefined" || typeof PerformanceObserver === "undefined") {
+    return () => {
+    };
+  }
+  const observers = [];
+  try {
+    const lcpObserver = new PerformanceObserver((list) => {
+      const entries = list.getEntries();
+      const last = entries[entries.length - 1];
+      if (last) {
+        emit({
+          type: "web-vital",
+          timestamp: Date.now(),
+          url: window.location.href,
+          metric: "LCP",
+          value: Math.round(last.startTime)
+        });
+      }
+    });
+    lcpObserver.observe({ type: "largest-contentful-paint", buffered: true });
+    observers.push(lcpObserver);
+  } catch {
+  }
+  try {
+    let clsValue = 0;
+    const clsObserver = new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        if (!entry.hadRecentInput) {
+          clsValue += entry.value ?? 0;
+        }
+      }
+      emit({
+        type: "web-vital",
+        timestamp: Date.now(),
+        url: window.location.href,
+        metric: "CLS",
+        value: Math.round(clsValue * 1e3) / 1e3
+      });
+    });
+    clsObserver.observe({ type: "layout-shift", buffered: true });
+    observers.push(clsObserver);
+  } catch {
+  }
+  return () => {
+    for (const obs of observers) {
+      obs.disconnect();
+    }
+  };
+}
+
+// src/debug/captures/memory.ts
+function installMemoryCapture(emit, intervalMs = 3e4) {
+  if (typeof window === "undefined") {
+    return () => {
+    };
+  }
+  const perf = performance;
+  if (!perf.memory) {
+    return () => {
+    };
+  }
+  const tick = () => {
+    const mem = perf.memory;
+    if (!mem) return;
+    emit({
+      type: "memory",
+      timestamp: Date.now(),
+      url: window.location.href,
+      usedJSHeapSize: mem.usedJSHeapSize,
+      totalJSHeapSize: mem.totalJSHeapSize,
+      jsHeapSizeLimit: mem.jsHeapSizeLimit
+    });
+  };
+  tick();
+  const id = setInterval(tick, intervalMs);
+  return () => {
+    clearInterval(id);
+  };
+}
+
+// src/debug/captures/hmr.ts
+var HMR_PATH_PATTERNS = ["/_next/webpack-hmr", "/__turbopack_hmr", "/_next/turbopack-hmr"];
+function isHmrUrl(url) {
+  return HMR_PATH_PATTERNS.some((p) => url.includes(p));
+}
+function makeEvent2(level, message, moduleName, loc) {
+  return {
+    type: "hmr",
+    level,
+    message,
+    moduleName,
+    loc,
+    timestamp: Date.now(),
+    url: typeof window !== "undefined" ? window.location.href : ""
+  };
+}
+function processHmrMessage(data, emit) {
+  try {
+    const msg = JSON.parse(data);
+    if (Array.isArray(msg.errors)) {
+      for (const err of msg.errors) {
+        emit(
+          makeEvent2(
+            "error",
+            typeof err === "string" ? err : err.message ?? String(err),
+            err.moduleName ?? err.moduleIdentifier,
+            err.loc ? String(err.loc) : void 0
+          )
+        );
+      }
+    }
+    if (Array.isArray(msg.warnings)) {
+      for (const warn of msg.warnings) {
+        emit(
+          makeEvent2(
+            "warning",
+            typeof warn === "string" ? warn : warn.message ?? String(warn),
+            warn.moduleName ?? warn.moduleIdentifier,
+            warn.loc ? String(warn.loc) : void 0
+          )
+        );
+      }
+    }
+    if (msg.action === "serverError" && msg.errorJSON) {
+      try {
+        const err = JSON.parse(msg.errorJSON);
+        emit(makeEvent2("error", err.message ?? String(err)));
+      } catch {
+        emit(makeEvent2("error", msg.errorJSON));
+      }
+    }
+    if ((msg.action === "turbopack-message" || msg.type === "turbopack-message") && msg.data?.diagnostics) {
+      for (const diag of msg.data.diagnostics) {
+        emit(
+          makeEvent2(
+            diag.category === "warning" ? "warning" : "error",
+            diag.message ?? String(diag),
+            diag.filePath,
+            diag.line != null ? `${diag.line}:${diag.column ?? 0}` : void 0
+          )
+        );
+      }
+    }
+  } catch {
+  }
+}
+function installWebSocketCapture(emit, cleanups) {
+  if (!window.WebSocket) return;
+  const OriginalWebSocket = window.WebSocket;
+  const trackedSockets = [];
+  const PatchedWebSocket = function(url, protocols) {
+    const ws = new OriginalWebSocket(url, protocols);
+    const urlStr = typeof url === "string" ? url : url.toString();
+    if (isHmrUrl(urlStr)) {
+      ws.addEventListener("message", (event) => {
+        if (typeof event.data === "string") {
+          processHmrMessage(event.data, emit);
+        }
+      });
+      trackedSockets.push(ws);
+    }
+    return ws;
+  };
+  PatchedWebSocket.prototype = OriginalWebSocket.prototype;
+  Object.defineProperty(PatchedWebSocket, "CONNECTING", { value: OriginalWebSocket.CONNECTING });
+  Object.defineProperty(PatchedWebSocket, "OPEN", { value: OriginalWebSocket.OPEN });
+  Object.defineProperty(PatchedWebSocket, "CLOSING", { value: OriginalWebSocket.CLOSING });
+  Object.defineProperty(PatchedWebSocket, "CLOSED", { value: OriginalWebSocket.CLOSED });
+  window.WebSocket = PatchedWebSocket;
+  cleanups.push(() => {
+    window.WebSocket = OriginalWebSocket;
+    for (const ws of trackedSockets) {
+      ws.close();
+    }
+    trackedSockets.length = 0;
+  });
+}
+function installEventSourceCapture(emit, cleanups) {
+  if (!window.EventSource) return;
+  const OriginalEventSource = window.EventSource;
+  const trackedSources = [];
+  const messageHandler = (event) => {
+    if (typeof event.data === "string") {
+      processHmrMessage(event.data, emit);
+    }
+  };
+  const PatchedEventSource = function(url, init) {
+    const es = new OriginalEventSource(url, init);
+    const urlStr = typeof url === "string" ? url : url.toString();
+    if (isHmrUrl(urlStr)) {
+      es.addEventListener("message", messageHandler);
+      trackedSources.push(es);
+    }
+    return es;
+  };
+  PatchedEventSource.prototype = OriginalEventSource.prototype;
+  Object.defineProperty(PatchedEventSource, "CONNECTING", {
+    value: OriginalEventSource.CONNECTING
+  });
+  Object.defineProperty(PatchedEventSource, "OPEN", { value: OriginalEventSource.OPEN });
+  Object.defineProperty(PatchedEventSource, "CLOSED", { value: OriginalEventSource.CLOSED });
+  window.EventSource = PatchedEventSource;
+  cleanups.push(() => {
+    window.EventSource = OriginalEventSource;
+    for (const es of trackedSources) {
+      es.close();
+    }
+    trackedSources.length = 0;
+  });
+}
+function installHmrCapture(emit) {
+  if (typeof window === "undefined") return () => {
+  };
+  const cleanups = [];
+  installWebSocketCapture(emit, cleanups);
+  installEventSourceCapture(emit, cleanups);
+  return () => {
+    for (const cleanup of cleanups) {
+      cleanup();
+    }
+  };
+}
+
+// src/debug/captures/long-animation-frames.ts
+function installLoafCapture(emit) {
+  if (typeof window === "undefined" || typeof PerformanceObserver === "undefined") {
+    return () => {
+    };
+  }
+  try {
+    const observer = new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        const scripts = (entry.scripts ?? []).map((s) => {
+          const script = s;
+          return {
+            invoker: script.invoker ?? "",
+            sourceURL: script.sourceURL ?? "",
+            sourceFunctionName: script.sourceFunctionName ?? "",
+            sourceCharPosition: script.sourceCharPosition ?? 0,
+            duration: Math.round(script.duration ?? 0)
+          };
+        });
+        emit({
+          type: "long-animation-frame",
+          timestamp: Date.now(),
+          url: window.location.href,
+          durationMs: Math.round(entry.duration),
+          blockingDurationMs: Math.round(
+            entry.blockingDuration ?? 0
+          ),
+          scripts
+        });
+      }
+    });
+    observer.observe({ type: "long-animation-frame", buffered: true });
+    return () => {
+      observer.disconnect();
+    };
+  } catch {
+    return () => {
+    };
+  }
+}
+
+// src/debug/browser-capture.ts
+var BrowserEventCapture = class {
+  constructor(config) {
+    this.buffer = [];
+    this.installed = false;
+    this.cleanups = [];
+    this.onEvent = null;
+    this.config = config ?? {};
+    this.maxEntries = config?.maxEntries ?? DEFAULT_CAPTURE_CONFIG.maxEntries;
+  }
+  setOnEvent(cb) {
+    this.onEvent = cb;
+  }
+  /**
+   * Install all enabled capture sub-modules.
+   * Safe to call multiple times (no-ops if already installed).
+   */
+  install() {
+    if (this.installed) return;
+    const cfg = { ...DEFAULT_CAPTURE_CONFIG, ...this.config };
+    const emit = (event) => {
+      this.buffer.push(event);
+      this.trim();
+      this.onEvent?.(event);
+    };
+    if (cfg.console) {
+      this.cleanups.push(installConsoleCapture(emit));
+    }
+    if (cfg.network) {
+      this.cleanups.push(installNetworkCapture(emit, cfg.networkOptions));
+    }
+    if (cfg.navigation) {
+      this.cleanups.push(installNavigationCapture(emit));
+    }
+    if (cfg.longTasks) {
+      this.cleanups.push(installLongTaskCapture(emit));
+    }
+    if (cfg.longAnimationFrames) {
+      this.cleanups.push(installLoafCapture(emit));
+    }
+    if (cfg.resourceErrors) {
+      this.cleanups.push(installResourceErrorCapture(emit));
+    }
+    if (cfg.webVitals) {
+      this.cleanups.push(installWebVitalsCapture(emit));
+    }
+    if (cfg.memory) {
+      this.cleanups.push(installMemoryCapture(emit, cfg.memoryIntervalMs));
+    }
+    if (cfg.hmr) {
+      this.cleanups.push(installHmrCapture(emit));
+    }
+    this.installed = true;
+  }
+  /**
+   * Uninstall all capture sub-modules.
+   */
+  uninstall() {
+    if (!this.installed) return;
+    for (const cleanup of this.cleanups) {
+      cleanup();
+    }
+    this.cleanups = [];
+    this.installed = false;
+  }
+  // -------------------------------------------------------------------------
+  // Manual event reporting (for events that can't be auto-captured)
+  // -------------------------------------------------------------------------
+  reportReactError(error, errorInfo) {
+    const event = {
+      type: "react-error",
+      timestamp: Date.now(),
+      url: typeof window !== "undefined" ? window.location.href : "",
+      message: error.message,
+      stack: error.stack,
+      componentStack: errorInfo.componentStack
+    };
+    this.buffer.push(event);
+    this.trim();
+    this.onEvent?.(event);
+  }
+  reportWsStateChange(prev, next, reconnectAttempt) {
+    if (next === "disconnected" || next === "error") {
+      const event = {
+        type: "ws-disconnection",
+        timestamp: Date.now(),
+        url: typeof window !== "undefined" ? window.location.href : "",
+        previousState: prev,
+        newState: next,
+        reconnectAttempt
+      };
+      this.buffer.push(event);
+      this.trim();
+      this.onEvent?.(event);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Query methods
+  // -------------------------------------------------------------------------
+  getSince(ts) {
+    return this.buffer.filter((e) => e.timestamp >= ts);
+  }
+  getRecent(n = 50) {
+    return this.buffer.slice(-n);
+  }
+  getByType(type) {
+    return this.buffer.filter((e) => e.type === type);
+  }
+  /**
+   * Get console errors since a timestamp (backward-compat for ActionExecutor).
+   */
+  getConsoleSince(ts) {
+    return this.buffer.filter((e) => (e.type === "console" || e.type === "hmr") && e.timestamp >= ts).map((e) => ({
+      timestamp: e.timestamp,
+      level: e.type === "hmr" ? e.level === "warning" ? "warn" : e.level : e.level,
+      message: e.message,
+      stack: e.stack
+    }));
+  }
+  /**
+   * Get recent console errors (backward-compat for ActionExecutor).
+   */
+  getConsoleRecent(n = 50) {
+    return this.buffer.filter((e) => e.type === "console" || e.type === "hmr").slice(-n).map((e) => ({
+      timestamp: e.timestamp,
+      level: e.type === "hmr" ? e.level === "warning" ? "warn" : e.level : e.level,
+      message: e.message,
+      stack: e.stack
+    }));
+  }
+  clear() {
+    this.buffer = [];
+  }
+  trim() {
+    if (this.buffer.length > this.maxEntries) {
+      this.buffer = this.buffer.slice(-this.maxEntries);
+    }
+  }
+};
+var UIBridgeContext = react.createContext(null);
+function UIBridgeProvider({
+  children,
+  features = {},
+  config = {},
+  onEvent,
+  onBrowserEvent,
+  browserCaptureConfig
+}) {
+  const registryRef = react.useRef(null);
+  const renderLogRef = react.useRef(null);
+  const metricsRef = react.useRef(null);
+  const browserCaptureRef = react.useRef(null);
+  const wsClientRef = react.useRef(null);
+  const [wsConnectionState, setWsConnectionState] = react.useState("disconnected");
+  const prevWsStateRef = react.useRef("disconnected");
+  if (!registryRef.current) {
+    registryRef.current = new UIBridgeRegistry({
+      verbose: config.verbose,
+      onEvent
+    });
+    setGlobalRegistry(registryRef.current);
+    if (features.renderLog) {
+      renderLogRef.current = createRenderLogManager({
+        maxEntries: config.maxLogEntries
+      });
+    }
+    if (features.debug) {
+      metricsRef.current = createMetricsCollector();
+    }
+    browserCaptureRef.current = new BrowserEventCapture(browserCaptureConfig);
+    browserCaptureRef.current.install();
+    if (config.websocket) {
+      const wsPort = config.websocketPort || config.serverPort || 9876;
       const wsUrl = `ws://localhost:${wsPort}`;
       wsClientRef.current = createWSClient({
         url: wsUrl,
@@ -3625,12 +5021,27 @@ function UIBridgeProvider({
         pingInterval: 3e4
       });
     }
+    if (typeof window !== "undefined") {
+      const w = window;
+      if (!w.__UI_BRIDGE__) {
+        w.__UI_BRIDGE__ = {};
+      }
+      w.__UI_BRIDGE__.specs = {
+        getGlobalSpecStore
+      };
+      w.__UI_BRIDGE__.browserCapture = browserCaptureRef.current;
+      w.__UI_BRIDGE__.consoleCapture = browserCaptureRef.current;
+    }
   }
   const registry = registryRef.current;
   const renderLog = renderLogRef.current || void 0;
   const metrics = metricsRef.current || void 0;
   const wsClient = wsClientRef.current || void 0;
-  const executor = react.useMemo(() => createActionExecutor(registry), [registry]);
+  const browserCapture = browserCaptureRef.current || void 0;
+  const executor = react.useMemo(
+    () => createActionExecutor(registry, browserCapture),
+    [registry, browserCapture]
+  );
   const workflowEngine = react.useMemo(
     () => createWorkflowEngine(registry, executor),
     [registry, executor]
@@ -3657,13 +5068,21 @@ function UIBridgeProvider({
   react.useEffect(() => {
     if (!wsClient) return;
     const unsubscribe = wsClient.onConnectionChange((state) => {
+      const prev = prevWsStateRef.current;
+      prevWsStateRef.current = state;
       setWsConnectionState(state);
+      browserCaptureRef.current?.reportWsStateChange(prev, state);
     });
     return unsubscribe;
   }, [wsClient]);
+  react.useEffect(() => {
+    browserCaptureRef.current?.setOnEvent(onBrowserEvent ?? null);
+  }, [onBrowserEvent]);
   react.useEffect(() => {
     return () => {
       renderLog?.stop();
+      browserCaptureRef.current?.setOnEvent(null);
+      browserCaptureRef.current?.uninstall();
       wsClient?.disconnect();
       resetGlobalRegistry();
     };
@@ -3698,6 +5117,10 @@ function UIBridgeProvider({
   const getElements = react.useCallback(() => registry.getAllElements(), [registry]);
   const getComponents = react.useCallback(() => registry.getAllComponents(), [registry]);
   const createSnapshot = react.useCallback(() => registry.createSnapshot(), [registry]);
+  const createSnapshotAsync = react.useCallback(
+    (batchSize) => registry.createSnapshotAsync(batchSize),
+    [registry]
+  );
   const on = react.useCallback(
     (type, listener) => registry.on(type, listener),
     [registry]
@@ -3720,6 +5143,7 @@ function UIBridgeProvider({
       getElements,
       getComponents,
       createSnapshot,
+      createSnapshotAsync,
       on,
       off,
       initialized: true,
@@ -3741,6 +5165,7 @@ function UIBridgeProvider({
       getElements,
       getComponents,
       createSnapshot,
+      createSnapshotAsync,
       on,
       off,
       wsConnect,
@@ -3980,6 +5405,20 @@ function useUIBridge() {
     }
     return context.createSnapshot();
   }, [context]);
+  const createSnapshotAsync = react.useCallback(
+    async (batchSize) => {
+      if (!context) {
+        return {
+          timestamp: Date.now(),
+          elements: [],
+          components: [],
+          workflows: []
+        };
+      }
+      return context.createSnapshotAsync(batchSize);
+    },
+    [context]
+  );
   const executeAction = react.useCallback(
     async (elementId, request) => {
       if (!context) {
@@ -4101,6 +5540,7 @@ function useUIBridge() {
     components,
     workflows,
     createSnapshot,
+    createSnapshotAsync,
     executeAction,
     executeComponentAction,
     find,
@@ -4516,6 +5956,305 @@ function useNavigationPath(targetStates) {
     return bridge.registry.findPath(targetStates);
   }, [bridge, targetStates]);
 }
+
+// src/react/content-discovery.ts
+var CONTENT_SELECTORS = [
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "p",
+  "li",
+  "td",
+  "th",
+  "label:not([for])",
+  "figcaption",
+  "caption",
+  "blockquote",
+  "pre",
+  "code",
+  "dd",
+  "dt",
+  '[role="heading"]',
+  '[role="status"]',
+  '[role="alert"]',
+  "[aria-live]",
+  "legend",
+  "summary",
+  "[data-content-role]"
+];
+var CONTENT_EXCLUDE_SELECTORS = [
+  "script",
+  "style",
+  "noscript",
+  "template",
+  '[aria-hidden="true"]',
+  "[data-no-register]",
+  ".sr-only",
+  ".visually-hidden"
+];
+function getDirectTextContent(element) {
+  let text = "";
+  for (const node of element.childNodes) {
+    if (node.nodeType === Node.TEXT_NODE) {
+      text += node.textContent || "";
+    }
+  }
+  return text.trim();
+}
+var SEMANTIC_CONTENT_TAGS = /* @__PURE__ */ new Set([
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "p",
+  "li",
+  "td",
+  "th",
+  "label",
+  "figcaption",
+  "caption",
+  "blockquote",
+  "pre",
+  "code",
+  "dd",
+  "dt",
+  "legend",
+  "summary"
+]);
+function isNoise(element) {
+  const text = getDirectTextContent(element);
+  const tag = element.tagName.toLowerCase();
+  if (!text && element.children.length > 0 && !SEMANTIC_CONTENT_TAGS.has(tag) && !element.hasAttribute("data-content-role")) {
+    return true;
+  }
+  const fullText = element.textContent?.trim() || "";
+  if (fullText.length === 1 && !/\w/.test(fullText)) {
+    return true;
+  }
+  return false;
+}
+function isContentVisible(element) {
+  const style = window.getComputedStyle(element);
+  if (style.display === "none" || style.visibility === "hidden") {
+    return false;
+  }
+  if (parseFloat(style.opacity) === 0) {
+    return false;
+  }
+  const rect = element.getBoundingClientRect();
+  return rect.width > 0 && rect.height > 0;
+}
+function shouldRegisterContent(element, options = {}, registeredIds) {
+  const minTextLength = options.minTextLength ?? 1;
+  const excludeSelectors = [
+    ...CONTENT_EXCLUDE_SELECTORS,
+    ...options.excludeContentSelectors || []
+  ];
+  for (const sel of excludeSelectors) {
+    if (element.matches(sel)) {
+      return false;
+    }
+  }
+  if (!isContentVisible(element)) {
+    return false;
+  }
+  const text = element.textContent?.trim() || "";
+  if (text.length < minTextLength) {
+    return false;
+  }
+  if (isNoise(element)) {
+    return false;
+  }
+  if (isInteractiveElement(element)) {
+    return false;
+  }
+  const id = generateContentId(element);
+  if (registeredIds.has(id)) {
+    return false;
+  }
+  if (options.contentRoles && options.contentRoles.length > 0) {
+    const metadata = inferContentMetadata(element);
+    if (!options.contentRoles.includes(metadata.contentRole)) {
+      return false;
+    }
+  }
+  return true;
+}
+function isInteractiveElement(element) {
+  const tag = element.tagName.toLowerCase();
+  const interactiveTags = ["button", "input", "select", "textarea", "a"];
+  if (interactiveTags.includes(tag)) return true;
+  const role = element.getAttribute("role");
+  const interactiveRoles = [
+    "button",
+    "link",
+    "checkbox",
+    "radio",
+    "menuitem",
+    "tab",
+    "switch",
+    "slider",
+    "spinbutton",
+    "combobox",
+    "listbox",
+    "option",
+    "textbox"
+  ];
+  if (role && interactiveRoles.includes(role)) return true;
+  if (element.getAttribute("contenteditable") === "true") return true;
+  if (element.hasAttribute("data-ui-element")) return true;
+  return false;
+}
+function inferContentType(element) {
+  const explicitRole = element.getAttribute("data-content-role");
+  if (explicitRole) return roleToContentType(explicitRole);
+  const tag = element.tagName.toLowerCase();
+  const role = element.getAttribute("role");
+  if (role === "heading") return "heading";
+  if (role === "status") return "status-message";
+  if (role === "alert") return "status-message";
+  if (/^h[1-6]$/.test(tag)) return "heading";
+  if (tag === "p") return "paragraph";
+  if (tag === "li") return "list-item";
+  if (tag === "td") return "table-cell";
+  if (tag === "th") return "table-header";
+  if (tag === "label") return "label";
+  if (tag === "figcaption" || tag === "caption") return "caption";
+  if (tag === "blockquote") return "blockquote";
+  if (tag === "pre" || tag === "code") return "code-block";
+  if (tag === "dd") return "description-text";
+  if (tag === "dt") return "label";
+  if (tag === "legend") return "label";
+  if (tag === "summary") return "label";
+  if (element.hasAttribute("aria-live")) return "status-message";
+  const classList = element.className?.toLowerCase() || "";
+  if (classList.includes("badge")) return "badge";
+  if (classList.includes("status")) return "status-message";
+  if (classList.includes("metric") || classList.includes("stat")) return "metric-value";
+  return "content-generic";
+}
+function roleToContentType(role) {
+  const map = {
+    heading: "heading",
+    "body-text": "paragraph",
+    "list-item": "list-item",
+    "table-cell": "table-cell",
+    "table-header": "table-header",
+    label: "label",
+    caption: "caption",
+    quote: "blockquote",
+    code: "code-block",
+    badge: "badge",
+    status: "status-message",
+    metric: "metric-value",
+    description: "description-text",
+    navigation: "nav-text",
+    generic: "content-generic"
+  };
+  return map[role] ?? "content-generic";
+}
+function contentTypeToRole(contentType) {
+  const map = {
+    heading: "heading",
+    paragraph: "body-text",
+    "list-item": "list-item",
+    "table-cell": "table-cell",
+    "table-header": "table-header",
+    label: "label",
+    caption: "caption",
+    blockquote: "quote",
+    "code-block": "code",
+    badge: "badge",
+    "status-message": "status",
+    "metric-value": "metric",
+    "description-text": "description",
+    "nav-text": "navigation",
+    "content-generic": "generic"
+  };
+  return map[contentType];
+}
+function inferContentMetadata(element) {
+  const contentType = inferContentType(element);
+  const explicitRole = element.getAttribute("data-content-role");
+  const contentRole = explicitRole ? explicitRole : contentTypeToRole(contentType);
+  const metadata = {
+    contentRole
+  };
+  const explicitLevel = element.getAttribute("data-content-level");
+  const tag = element.tagName.toLowerCase();
+  const role = element.getAttribute("role");
+  if (explicitLevel) {
+    metadata.headingLevel = parseInt(explicitLevel, 10);
+  } else if (/^h([1-6])$/.test(tag)) {
+    metadata.headingLevel = parseInt(tag[1], 10);
+  } else if (role === "heading") {
+    const ariaLevel = element.getAttribute("aria-level");
+    metadata.headingLevel = ariaLevel ? parseInt(ariaLevel, 10) : 2;
+  }
+  if (element.hasAttribute("aria-live") || role === "status" || role === "alert") {
+    metadata.dynamic = true;
+  }
+  if (tag === "td" || tag === "th") {
+    const row = element.closest("tr");
+    const table = element.closest("table");
+    if (row && table) {
+      const rows = Array.from(table.querySelectorAll("tr"));
+      const rowIndex = rows.indexOf(row);
+      const cells = Array.from(row.children);
+      const colIndex = cells.indexOf(element);
+      metadata.structuralContext = `table > row ${rowIndex} > col ${colIndex}`;
+    }
+  }
+  if (metadata.dynamic) {
+    const text = element.textContent?.trim() || "";
+    if (text.length > 10) {
+      metadata.stableTextPrefix = text.substring(0, 10);
+    }
+  }
+  return metadata;
+}
+function slugify(text, maxLength = 30) {
+  return text.toLowerCase().replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").slice(0, maxLength).replace(/-+$/, "");
+}
+function generateContentId(element) {
+  const explicitId = element.getAttribute("data-content-id");
+  if (explicitId) return explicitId;
+  const contentType = inferContentType(element);
+  const tag = element.tagName.toLowerCase();
+  const contentLabel = element.getAttribute("data-content-label");
+  if (contentType === "heading") {
+    const level = element.getAttribute("data-content-level") || (/^h([1-6])$/.test(tag) ? tag[1] : element.getAttribute("aria-level") || "2");
+    const text = contentLabel || element.textContent?.trim() || "";
+    const slug = slugify(text);
+    return `heading-${level}-${slug || "untitled"}`;
+  }
+  if (contentType === "table-cell" || contentType === "table-header") {
+    const row = element.closest("tr");
+    const table = element.closest("table");
+    if (row && table) {
+      const rows = Array.from(table.querySelectorAll("tr"));
+      const rowIndex = rows.indexOf(row);
+      const cells = Array.from(row.children);
+      const colIndex = cells.indexOf(element);
+      const tableAnchor = table.getAttribute("data-ui-id") || table.getAttribute("data-testid") || table.id || "table";
+      return `cell-r${rowIndex}-c${colIndex}-${tableAnchor}`;
+    }
+  }
+  const parent = element.parentElement;
+  const anchorId = parent?.getAttribute("data-ui-id") || parent?.getAttribute("data-testid") || parent?.id || "";
+  const siblings = parent ? Array.from(parent.querySelectorAll(`:scope > ${tag}`)) : [];
+  const siblingIndex = siblings.indexOf(element);
+  const textSlug = slugify(contentLabel || element.textContent?.trim() || "", 20);
+  const anchor = anchorId ? slugify(anchorId, 15) : textSlug;
+  return `content-${contentType}-${anchor || "unknown"}-${siblingIndex >= 0 ? siblingIndex : 0}`;
+}
+
+// src/react/useAutoRegister.ts
 var INTERACTIVE_SELECTORS2 = [
   "a[href]",
   "button",
@@ -4710,12 +6449,17 @@ function useAutoRegister(options = {}) {
     excludeSelectors = [],
     generateId: customGenerateId,
     onRegister,
-    onUnregister
+    onUnregister,
+    contentDiscovery
   } = options;
+  const contentEnabled = contentDiscovery?.enabled !== false;
   const bridge = useUIBridgeOptional();
   const registeredElementsRef = react.useRef(/* @__PURE__ */ new Map());
+  const registeredContentElementsRef = react.useRef(/* @__PURE__ */ new Map());
   const pendingRegistrationsRef = react.useRef(/* @__PURE__ */ new Set());
+  const pendingContentRegistrationsRef = react.useRef(/* @__PURE__ */ new Set());
   const debounceTimeoutRef = react.useRef(null);
+  const contentDebounceTimeoutRef = react.useRef(null);
   const shouldRegister = react.useCallback(
     (element) => {
       if (!includeHidden && !isElementVisible2(element)) {
@@ -4783,6 +6527,41 @@ function useAutoRegister(options = {}) {
     },
     [bridge, onUnregister]
   );
+  const registerContentElement = react.useCallback(
+    (element) => {
+      if (!bridge?.registry || registeredContentElementsRef.current.has(element)) {
+        return;
+      }
+      const maxElements = contentDiscovery?.maxContentElements ?? 500;
+      if (registeredContentElementsRef.current.size >= maxElements) {
+        return;
+      }
+      const id = generateContentId(element);
+      const existing = bridge.registry.getElement(id);
+      if (existing) {
+        return;
+      }
+      const contentType = inferContentType(element);
+      const metadata = inferContentMetadata(element);
+      const label = element.getAttribute("data-content-label") || element.textContent?.trim().substring(0, 50) || void 0;
+      bridge.registry.registerContentElement(id, element, {
+        contentType,
+        contentMetadata: metadata,
+        label
+      });
+      registeredContentElementsRef.current.set(element, id);
+    },
+    [bridge, contentDiscovery?.maxContentElements]
+  );
+  const unregisterContentElement = react.useCallback(
+    (element) => {
+      const id = registeredContentElementsRef.current.get(element);
+      if (!id || !bridge?.registry) return;
+      bridge.registry.unregisterElement(id);
+      registeredContentElementsRef.current.delete(element);
+    },
+    [bridge]
+  );
   const processPendingRegistrations = react.useCallback(() => {
     pendingRegistrationsRef.current.forEach((element) => {
       if (shouldRegister(element)) {
@@ -4791,6 +6570,15 @@ function useAutoRegister(options = {}) {
     });
     pendingRegistrationsRef.current.clear();
   }, [shouldRegister, registerElement]);
+  const processPendingContentRegistrations = react.useCallback(() => {
+    const registeredIds = new Set(registeredContentElementsRef.current.values());
+    pendingContentRegistrationsRef.current.forEach((element) => {
+      if (shouldRegisterContent(element, contentDiscovery, registeredIds)) {
+        registerContentElement(element);
+      }
+    });
+    pendingContentRegistrationsRef.current.clear();
+  }, [contentDiscovery, registerContentElement]);
   const queueRegistration = react.useCallback(
     (element) => {
       pendingRegistrationsRef.current.add(element);
@@ -4801,6 +6589,20 @@ function useAutoRegister(options = {}) {
     },
     [debounceMs, processPendingRegistrations]
   );
+  const queueContentRegistration = react.useCallback(
+    (element) => {
+      pendingContentRegistrationsRef.current.add(element);
+      if (contentDebounceTimeoutRef.current) {
+        clearTimeout(contentDebounceTimeoutRef.current);
+      }
+      const contentDebounceMs = contentDiscovery?.contentDebounceMs ?? 250;
+      contentDebounceTimeoutRef.current = setTimeout(
+        processPendingContentRegistrations,
+        contentDebounceMs
+      );
+    },
+    [contentDiscovery?.contentDebounceMs, processPendingContentRegistrations]
+  );
   const scanAndRegister = react.useCallback(
     (rootElement) => {
       const allSelectors = [...INTERACTIVE_SELECTORS2, ...includeSelectors].join(", ");
@@ -4810,8 +6612,28 @@ function useAutoRegister(options = {}) {
           queueRegistration(element);
         }
       });
+      if (contentEnabled) {
+        const contentSelectors = [
+          ...CONTENT_SELECTORS,
+          ...contentDiscovery?.includeContentSelectors || []
+        ].join(", ");
+        const contentElements = rootElement.querySelectorAll(contentSelectors);
+        const registeredIds = new Set(registeredContentElementsRef.current.values());
+        contentElements.forEach((element) => {
+          if (shouldRegisterContent(element, contentDiscovery, registeredIds)) {
+            queueContentRegistration(element);
+          }
+        });
+      }
     },
-    [includeSelectors, shouldRegister, queueRegistration]
+    [
+      includeSelectors,
+      shouldRegister,
+      queueRegistration,
+      contentEnabled,
+      contentDiscovery,
+      queueContentRegistration
+    ]
   );
   const handleMutations = react.useCallback(
     (mutations) => {
@@ -4829,6 +6651,22 @@ function useAutoRegister(options = {}) {
                 queueRegistration(descendant);
               }
             });
+            if (contentEnabled) {
+              const contentSelectors = [
+                ...CONTENT_SELECTORS,
+                ...contentDiscovery?.includeContentSelectors || []
+              ].join(", ");
+              const registeredIds = new Set(registeredContentElementsRef.current.values());
+              if (shouldRegisterContent(element, contentDiscovery, registeredIds)) {
+                queueContentRegistration(element);
+              }
+              const contentDescendants = element.querySelectorAll(contentSelectors);
+              contentDescendants.forEach((descendant) => {
+                if (shouldRegisterContent(descendant, contentDiscovery, registeredIds)) {
+                  queueContentRegistration(descendant);
+                }
+              });
+            }
           }
         });
         mutation.removedNodes.forEach((node) => {
@@ -4837,17 +6675,32 @@ function useAutoRegister(options = {}) {
             if (registeredElementsRef.current.has(element)) {
               unregisterElement(element);
             }
+            if (registeredContentElementsRef.current.has(element)) {
+              unregisterContentElement(element);
+            }
             const descendants = element.querySelectorAll("*");
             descendants.forEach((descendant) => {
               if (registeredElementsRef.current.has(descendant)) {
                 unregisterElement(descendant);
               }
+              if (registeredContentElementsRef.current.has(descendant)) {
+                unregisterContentElement(descendant);
+              }
             });
           }
         });
       });
     },
-    [shouldRegister, queueRegistration, unregisterElement, includeSelectors]
+    [
+      shouldRegister,
+      queueRegistration,
+      unregisterElement,
+      includeSelectors,
+      contentEnabled,
+      contentDiscovery,
+      queueContentRegistration,
+      unregisterContentElement
+    ]
   );
   react.useEffect(() => {
     if (!enabled || !bridge?.registry) return;
@@ -4863,10 +6716,17 @@ function useAutoRegister(options = {}) {
       if (debounceTimeoutRef.current) {
         clearTimeout(debounceTimeoutRef.current);
       }
+      if (contentDebounceTimeoutRef.current) {
+        clearTimeout(contentDebounceTimeoutRef.current);
+      }
       registeredElementsRef.current.forEach((id, _element) => {
         bridge.registry.unregisterElement(id);
       });
       registeredElementsRef.current.clear();
+      registeredContentElementsRef.current.forEach((id, _element) => {
+        bridge.registry.unregisterElement(id);
+      });
+      registeredContentElementsRef.current.clear();
     };
   }, [enabled, bridge, root, scanAndRegister, handleMutations]);
 }
@@ -4881,7 +6741,8 @@ function AutoRegisterProvider({
   excludeSelectors = [],
   generateId: generateId4,
   onRegister,
-  onUnregister
+  onUnregister,
+  contentDiscovery
 }) {
   const containerRef = react.useRef(null);
   useAutoRegister({
@@ -4894,7 +6755,8 @@ function AutoRegisterProvider({
     excludeSelectors,
     generateId: generateId4,
     onRegister,
-    onUnregister
+    onUnregister,
+    contentDiscovery
   });
   if (scopeToChildren) {
     return /* @__PURE__ */ jsxRuntime.jsx("div", { ref: containerRef, style: { display: "contents" }, children });
@@ -4902,6 +6764,253 @@ function AutoRegisterProvider({
   return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children });
 }
 
+// src/annotations/types.ts
+var ANNOTATION_CONFIG_VERSION = "1.0.0";
+
+// src/annotations/store.ts
+var AnnotationStore = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+    this.listeners = /* @__PURE__ */ new Set();
+  }
+  /**
+   * Get an annotation by element ID.
+   */
+  get(elementId) {
+    return this.store.get(elementId);
+  }
+  /**
+   * Get all annotations as a record.
+   */
+  getAll() {
+    const result = {};
+    for (const [id, annotation] of this.store) {
+      result[id] = annotation;
+    }
+    return result;
+  }
+  /**
+   * Set an annotation for an element. Auto-sets `updatedAt`.
+   */
+  set(elementId, annotation) {
+    const updated = {
+      ...annotation,
+      updatedAt: Date.now()
+    };
+    this.store.set(elementId, updated);
+    this.emit({
+      type: "annotation:set",
+      elementId,
+      annotation: updated,
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Delete an annotation by element ID.
+   *
+   * @returns true if the annotation existed and was deleted
+   */
+  delete(elementId) {
+    const existed = this.store.delete(elementId);
+    if (existed) {
+      this.emit({
+        type: "annotation:deleted",
+        elementId,
+        timestamp: Date.now()
+      });
+    }
+    return existed;
+  }
+  /**
+   * Check if an annotation exists for an element.
+   */
+  has(elementId) {
+    return this.store.has(elementId);
+  }
+  /**
+   * Get the number of stored annotations.
+   */
+  get count() {
+    return this.store.size;
+  }
+  /**
+   * Clear all annotations.
+   */
+  clear() {
+    this.store.clear();
+    this.emit({
+      type: "annotation:cleared",
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Import annotations from a config object.
+   *
+   * Merges with existing annotations (new values overwrite per element ID).
+   *
+   * @returns Number of annotations imported
+   *
+   * @example
+   * ```ts
+   * const config: AnnotationConfig = {
+   *   version: '1.0.0',
+   *   annotations: {
+   *     'btn-1': { description: 'Submit button', tags: ['form'] },
+   *     'input-1': { description: 'Name field' },
+   *   },
+   * };
+   * const count = store.importConfig(config); // 2
+   * ```
+   */
+  importConfig(config) {
+    let count = 0;
+    for (const [id, annotation] of Object.entries(config.annotations)) {
+      this.store.set(id, {
+        ...annotation,
+        updatedAt: annotation.updatedAt ?? Date.now()
+      });
+      count++;
+    }
+    this.emit({
+      type: "annotation:imported",
+      count,
+      timestamp: Date.now()
+    });
+    return count;
+  }
+  /**
+   * Export all annotations as a config object.
+   *
+   * The returned object can be serialized to JSON and saved to a file,
+   * then later re-imported with {@link importConfig}.
+   *
+   * @param metadata - Optional metadata to include (appName, description, etc.)
+   * @returns AnnotationConfig with all current annotations
+   *
+   * @example
+   * ```ts
+   * const config = store.exportConfig({ appName: 'MyApp' });
+   * // config.version === '1.0.0'
+   * // config.annotations === { 'btn-1': { ... }, 'input-1': { ... } }
+   * // config.metadata === { appName: 'MyApp', exportedAt: 1706900000000 }
+   *
+   * // Save to file
+   * fs.writeFileSync('annotations.json', JSON.stringify(config, null, 2));
+   * ```
+   */
+  exportConfig(metadata) {
+    return {
+      version: ANNOTATION_CONFIG_VERSION,
+      annotations: this.getAll(),
+      metadata: {
+        ...metadata,
+        exportedAt: Date.now()
+      }
+    };
+  }
+  /**
+   * Compute annotation coverage against a set of known element IDs.
+   *
+   * Compares the store's annotations against the provided list of element IDs
+   * to determine what percentage of elements have been annotated.
+   *
+   * @param allElementIds - Array of all known element IDs in the UI
+   * @returns Coverage statistics including percentages and lists of annotated/unannotated IDs
+   *
+   * @example
+   * ```ts
+   * store.set('btn-1', { description: 'Submit' });
+   * store.set('input-1', { description: 'Name' });
+   *
+   * const coverage = store.getCoverage(['btn-1', 'input-1', 'input-2', 'link-1']);
+   * // coverage.totalElements === 4
+   * // coverage.annotatedElements === 2
+   * // coverage.coveragePercent === 50
+   * // coverage.annotatedIds === ['btn-1', 'input-1']
+   * // coverage.unannotatedIds === ['input-2', 'link-1']
+   * ```
+   */
+  getCoverage(allElementIds) {
+    const annotatedIds = [];
+    const unannotatedIds = [];
+    for (const id of allElementIds) {
+      if (this.store.has(id)) {
+        annotatedIds.push(id);
+      } else {
+        unannotatedIds.push(id);
+      }
+    }
+    const total = allElementIds.length;
+    return {
+      totalElements: total,
+      annotatedElements: annotatedIds.length,
+      coveragePercent: total > 0 ? annotatedIds.length / total * 100 : 0,
+      annotatedIds,
+      unannotatedIds,
+      timestamp: Date.now()
+    };
+  }
+  /**
+   * Subscribe to annotation events.
+   *
+   * The listener is called whenever annotations are set, deleted, imported,
+   * or cleared. Returns an unsubscribe function to stop listening.
+   *
+   * @param listener - Callback function receiving {@link AnnotationEvent} objects
+   * @returns Unsubscribe function - call it to remove the listener
+   *
+   * @example
+   * ```ts
+   * const unsubscribe = store.on((event) => {
+   *   if (event.type === 'annotation:set') {
+   *     console.log(`Element ${event.elementId} annotated:`, event.annotation);
+   *   }
+   * });
+   *
+   * store.set('btn-1', { description: 'Submit' });
+   * // Logs: "Element btn-1 annotated: { description: 'Submit', updatedAt: ... }"
+   *
+   * unsubscribe(); // Stop listening
+   * ```
+   */
+  on(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /**
+   * Emit an event to all listeners.
+   */
+  emit(event) {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+      }
+    }
+  }
+};
+var globalStore2 = null;
+function getGlobalAnnotationStore() {
+  if (!globalStore2) {
+    globalStore2 = new AnnotationStore();
+  }
+  return globalStore2;
+}
+
+// src/react/useUIAnnotation.ts
+function useUIAnnotation(elementId, annotation) {
+  const serializedRef = react.useRef("");
+  react.useEffect(() => {
+    const serialized = JSON.stringify(annotation);
+    if (serialized !== serializedRef.current) {
+      serializedRef.current = serialized;
+      getGlobalAnnotationStore().set(elementId, annotation);
+    }
+  }, [elementId, annotation]);
+}
+
 exports.AutoRegisterProvider = AutoRegisterProvider;
 exports.UIBridgeProvider = UIBridgeProvider;
 exports.useActiveStates = useActiveStates;
@@ -4911,6 +7020,7 @@ exports.useCanNavigateTo = useCanNavigateTo;
 exports.useNavigationPath = useNavigationPath;
 exports.useStateSnapshot = useStateSnapshot;
 exports.useTransitions = useTransitions;
+exports.useUIAnnotation = useUIAnnotation;
 exports.useUIBridge = useUIBridge;
 exports.useUIBridgeContext = useUIBridgeContext;
 exports.useUIBridgeOptional = useUIBridgeOptional;