@qontinui/ui-bridge-native 0.6.1 → 0.6.3

package/dist/index.js

@@ -351,6 +351,51 @@ var NativeUIBridgeRegistry = class {
       this.emit("element:stateChanged", { id, state: newState });
     }
   }
+  /**
+   * Update an element's descriptive metadata (label / accessibilityLabel /
+   * testId). Sister to {@link updateElementState} (which carries layout +
+   * visibility) and {@link updateElementProps} (which carries event handlers).
+   *
+   * Idempotent — if every passed field equals the existing value, the call
+   * returns without mutating the entry or emitting an event. This keeps
+   * `useUIElement().updateLabel(...)` cheap when consumers re-publish from a
+   * render path that produces the same string on every tick.
+   *
+   * Returns `true` when the entry was mutated, `false` otherwise. Callers
+   * that want to gate a `console.warn` on no-op invocations can use the
+   * return value instead of recomputing equality.
+   */
+  updateElementMeta(id, meta) {
+    const element = this.elements.get(id);
+    if (!element) return false;
+    const currentIdentifier = element.getIdentifier();
+    const nextLabel = meta.label !== void 0 ? meta.label : element.label;
+    const nextAccessibilityLabel = meta.accessibilityLabel !== void 0 ? meta.accessibilityLabel : currentIdentifier.accessibilityLabel;
+    const nextTestId = meta.testId !== void 0 ? meta.testId : currentIdentifier.testId;
+    const labelChanged = nextLabel !== element.label;
+    const accessibilityLabelChanged = nextAccessibilityLabel !== currentIdentifier.accessibilityLabel;
+    const testIdChanged = nextTestId !== currentIdentifier.testId;
+    if (!labelChanged && !accessibilityLabelChanged && !testIdChanged) {
+      return false;
+    }
+    const updated = {
+      ...element,
+      label: nextLabel,
+      getIdentifier: () => ({
+        uiId: id,
+        testId: nextTestId,
+        accessibilityLabel: nextAccessibilityLabel,
+        treePath: currentIdentifier.treePath
+      })
+    };
+    this.elements.set(id, updated);
+    this.emit("element:registered", {
+      id,
+      type: element.type,
+      label: nextLabel
+    });
+    return true;
+  }
   /**
    * Update element props (for action execution)
    */
@@ -1783,6 +1828,245 @@ function createDesignHandlers(registry) {
   };
 }
 
+// src/server/page-health.ts
+var GRID_SIZE = 20;
+var NAV_TYPES = /* @__PURE__ */ new Set(["button", "heading", "badge", "status-message"]);
+var SKIP_TEXT_TYPES = /* @__PURE__ */ new Set(["button", "link", "tab", "menuitem"]);
+var INTERACTIVE_TYPES = /* @__PURE__ */ new Set([
+  "button",
+  "input",
+  "switch",
+  "checkbox",
+  "radio",
+  "touchable",
+  "listItem"
+]);
+var ERROR_PHRASES = [
+  "error occurred",
+  "failed to",
+  "exception",
+  "crash",
+  "unavailable",
+  "something went wrong",
+  "could not"
+];
+var LOADING_PHRASES = [
+  "loading",
+  "starting",
+  "connecting",
+  "please wait",
+  "initializing",
+  "fetching"
+];
+var EMPTY_PHRASES = [
+  "no data",
+  "no results",
+  "nothing here",
+  "empty",
+  "no items",
+  "get started"
+];
+function severityRank(s) {
+  if (s === "CRITICAL") return 3;
+  if (s === "WARNING") return 2;
+  return 1;
+}
+function worstSeverity(findings) {
+  let worst = "OK";
+  for (const f of findings) {
+    if (severityRank(f.severity) > severityRank(worst)) {
+      worst = f.severity;
+    }
+  }
+  return worst;
+}
+function truncate(s, n) {
+  if (s.length <= n) return s;
+  return [...s].slice(0, n).join("");
+}
+function normalizeRect(state, viewport) {
+  const layout = state.layout;
+  if (!layout) return null;
+  if (viewport.width <= 0 || viewport.height <= 0) return null;
+  const px = layout.pageX ?? layout.x;
+  const py = layout.pageY ?? layout.y;
+  return {
+    x: px / viewport.width,
+    y: py / viewport.height,
+    width: layout.width / viewport.width,
+    height: layout.height / viewport.height
+  };
+}
+function diagnosePageHealth(elements, viewport) {
+  const findings = [];
+  const projected = elements.map((el) => ({
+    el,
+    rect: el.state.visible ? normalizeRect(el.state, viewport) : null
+  }));
+  const visible = projected.filter((p) => p.rect !== null);
+  const grid = Array.from(
+    { length: GRID_SIZE },
+    () => Array.from({ length: GRID_SIZE }, () => false)
+  );
+  for (const { rect } of visible) {
+    const colStart = Math.max(0, Math.floor(rect.x * GRID_SIZE));
+    const colEnd = Math.min(GRID_SIZE, Math.ceil((rect.x + rect.width) * GRID_SIZE));
+    const rowStart = Math.max(0, Math.floor(rect.y * GRID_SIZE));
+    const rowEnd = Math.min(GRID_SIZE, Math.ceil((rect.y + rect.height) * GRID_SIZE));
+    for (let r = rowStart; r < rowEnd; r++) {
+      for (let c = colStart; c < colEnd; c++) {
+        grid[r][c] = true;
+      }
+    }
+  }
+  const totalCells = GRID_SIZE * GRID_SIZE;
+  const halfCells = totalCells / 2;
+  let filled = 0;
+  let leftFilled = 0;
+  let rightFilled = 0;
+  const half = GRID_SIZE / 2;
+  for (let r = 0; r < GRID_SIZE; r++) {
+    for (let c = 0; c < GRID_SIZE; c++) {
+      if (grid[r][c]) {
+        filled++;
+        if (c < half) leftFilled++;
+        else rightFilled++;
+      }
+    }
+  }
+  const coveragePct = Math.round(filled / totalCells * 100);
+  const leftHalfPct = Math.round(leftFilled / halfCells * 100);
+  const rightHalfPct = Math.round(rightFilled / halfCells * 100);
+  let spatialSeverity = "OK";
+  if (coveragePct < 15) spatialSeverity = "CRITICAL";
+  else if (coveragePct < 30) spatialSeverity = "WARNING";
+  if (rightHalfPct < 5 && leftHalfPct > 20) spatialSeverity = "CRITICAL";
+  findings.push({
+    check: "spatial_coverage",
+    severity: spatialSeverity,
+    detail: `Elements cover ${coveragePct}% of viewport. Left=${leftHalfPct}%, Right=${rightHalfPct}%`,
+    data: {
+      coverage_pct: coveragePct,
+      left_half_pct: leftHalfPct,
+      right_half_pct: rightHalfPct
+    }
+  });
+  let sidebar = 0;
+  let header = 0;
+  let content = 0;
+  for (const { rect } of visible) {
+    const cx = rect.x + rect.width / 2;
+    const cy = rect.y + rect.height / 2;
+    if (cx < 0.2) sidebar++;
+    else if (cy < 0.08) header++;
+    else content++;
+  }
+  let layoutSeverity = "OK";
+  if (content === 0) layoutSeverity = "CRITICAL";
+  else if (content < 3) layoutSeverity = "WARNING";
+  findings.push({
+    check: "layout_regions",
+    severity: layoutSeverity,
+    detail: `sidebar=${sidebar}, header=${header}, content=${content}`,
+    data: { sidebar, header, content }
+  });
+  const typeCounts = {};
+  for (const el of elements) {
+    const t = el.type || "unknown";
+    typeCounts[t] = (typeCounts[t] ?? 0) + 1;
+  }
+  const allNav = elements.length > 5 && Object.keys(typeCounts).every((k) => NAV_TYPES.has(k));
+  const diversitySeverity = allNav ? "WARNING" : "OK";
+  findings.push({
+    check: "element_diversity",
+    severity: diversitySeverity,
+    detail: `${Object.keys(typeCounts).length} type(s) across ${elements.length} elements${allNav ? " (navigation-only)" : ""}`,
+    data: { types: typeCounts }
+  });
+  const detectedErrors = [];
+  const detectedLoading = [];
+  const detectedEmpty = [];
+  const detectedCss = [];
+  for (const el of elements) {
+    const elType = el.type ?? "";
+    if (SKIP_TEXT_TYPES.has(elType)) continue;
+    const text = (el.state.textContent ?? "").toString();
+    if (!text) continue;
+    const textLower = text.toLowerCase();
+    for (const p of ERROR_PHRASES) {
+      if (textLower.includes(p)) {
+        detectedErrors.push(truncate(text, 120));
+        break;
+      }
+    }
+    for (const p of LOADING_PHRASES) {
+      if (textLower.includes(p)) {
+        detectedLoading.push(truncate(text, 120));
+        break;
+      }
+    }
+    for (const p of EMPTY_PHRASES) {
+      if (textLower.includes(p)) {
+        detectedEmpty.push(truncate(text, 120));
+        break;
+      }
+    }
+  }
+  let textSeverity = "OK";
+  if (detectedErrors.length > 0) textSeverity = "CRITICAL";
+  else if (detectedLoading.length > 0 || detectedEmpty.length > 0) textSeverity = "WARNING";
+  findings.push({
+    check: "text_signals",
+    severity: textSeverity,
+    detail: `errors=${detectedErrors.length}, loading=${detectedLoading.length}, empty=${detectedEmpty.length}, css_signals=${detectedCss.length}`,
+    data: {
+      errors: detectedErrors,
+      loading: detectedLoading,
+      empty: detectedEmpty,
+      css_signals: detectedCss
+    }
+  });
+  let interactiveTotal = 0;
+  let interactiveDisabled = 0;
+  for (const el of elements) {
+    if (!INTERACTIVE_TYPES.has(el.type)) continue;
+    interactiveTotal++;
+    if (el.state.enabled === false) interactiveDisabled++;
+  }
+  const interactiveSeverity = interactiveTotal > 0 && interactiveDisabled / interactiveTotal > 0.5 ? "WARNING" : "OK";
+  findings.push({
+    check: "interactive_readiness",
+    severity: interactiveSeverity,
+    detail: `${interactiveTotal} interactive elements, ${interactiveDisabled} disabled`,
+    data: { total: interactiveTotal, disabled: interactiveDisabled }
+  });
+  let zeroSize = 0;
+  let outsideViewport = 0;
+  for (const { rect } of visible) {
+    if (rect.width === 0 || rect.height === 0) zeroSize++;
+    if (rect.x + rect.width < 0 || rect.y + rect.height < 0 || rect.x > 1 || rect.y > 1) {
+      outsideViewport++;
+    }
+  }
+  const anomalySeverity = zeroSize > 0 || outsideViewport > 0 ? "WARNING" : "OK";
+  findings.push({
+    check: "visual_anomalies",
+    severity: anomalySeverity,
+    detail: `zero_size=${zeroSize}, outside_viewport=${outsideViewport}`,
+    data: { zero_size: zeroSize, outside_viewport: outsideViewport }
+  });
+  const heatmap = grid.map(
+    (row) => row.map((cell) => cell ? "#" : ".").join("")
+  );
+  return {
+    summary: worstSeverity(findings),
+    findings,
+    heatmap,
+    element_count: elements.length,
+    visible_count: visible.length
+  };
+}
+
 // src/server/handlers.ts
 async function executeWorkflowStep(step, registry, executor) {
   const startTime = Date.now();
@@ -2167,6 +2451,25 @@ function createServerHandlers(registry, executor, config) {
       const snapshot = registry.createSnapshot(void 0, { visibleOnly, currentRouteOnly });
       return success2(snapshot);
     },
+    getPageHealth: async (ctx) => {
+      const bodyViewport = ctx.body?.viewport;
+      let viewport = bodyViewport;
+      if (!viewport) {
+        try {
+          const { Dimensions: Dimensions2 } = __require("react-native");
+          const win = Dimensions2.get("window");
+          viewport = { width: win.width, height: win.height };
+        } catch {
+          viewport = { width: 0, height: 0 };
+        }
+      }
+      const elements = registry.getAllElements().map((e) => ({
+        type: e.type,
+        state: e.getState()
+      }));
+      const report = diagnosePageHealth(elements, viewport);
+      return success2(report);
+    },
     // Workflows
     getWorkflows: async () => {
       const workflows = registry.getAllWorkflows().map((w) => ({
@@ -2915,6 +3218,10 @@ var WS_ROUTES = [
   { pattern: "ai/find", handler: "find", httpMethods: ["POST"] },
   { pattern: "control/snapshot", handler: "getSnapshot", httpMethods: ["GET"] },
   { pattern: "control/discover", handler: "getSnapshot" },
+  // Page health — accepts both GET and POST so the canonical skill invocation
+  // (`POST .../control/page-health` with an empty body) and ad-hoc curls both
+  // work without a body-shape gotcha.
+  { pattern: "control/page-health", handler: "getPageHealth", httpMethods: ["GET", "POST"] },
   // Workflows
   { pattern: "control/workflows", handler: "getWorkflows", httpMethods: ["GET"] },
   { pattern: "control/workflow/:id/run", handler: "runWorkflow", httpMethods: ["POST"] },
@@ -3019,6 +3326,7 @@ var HANDLER_DESCRIPTIONS = {
   executeComponentAction: "Invoke a component action directly (preferred over button clicks)",
   find: "AI-powered element search by natural-language query",
   getSnapshot: "Full snapshot: elements + route + state. Supports ?visibleOnly=true and ?currentRouteOnly=true",
+  getPageHealth: 'Holistic page health diagnostic over current snapshot elements (spatial coverage, layout regions, text/anomaly signals, heatmap). Optional body: { viewport?: { width, height } } to override Dimensions.get("window").',
   getWorkflows: "List registered workflows",
   runWorkflow: "Trigger a workflow by id",
   pageRefresh: "Reload the current route",
@@ -5166,6 +5474,7 @@ function flattenStateStyles(stateStyles) {
   return Object.keys(result).length > 0 ? result : void 0;
 }
 var warnedDeadButtonIds = /* @__PURE__ */ new Set();
+var warnedRedundantUpdateLabelIds = /* @__PURE__ */ new Set();
 function scheduleDeadButtonWarning(bridge, id, type) {
   if (type !== "button" && type !== "pressable") return;
   if (warnedDeadButtonIds.has(id)) return;
@@ -5394,6 +5703,23 @@ function useUIElement(options) {
     },
     [bridge, id]
   );
+  const updateLabel = react.useCallback(
+    (newLabel) => {
+      if (!bridge || !registered) return;
+      const changed = bridge.registry.updateElementMeta(id, {
+        label: newLabel,
+        accessibilityLabel: newLabel,
+        testId: id
+      });
+      if (!changed && !warnedRedundantUpdateLabelIds.has(id)) {
+        warnedRedundantUpdateLabelIds.add(id);
+        console.warn(
+          `[UI Bridge] updateLabel("${newLabel}") on element "${id}" was a no-op (label unchanged). Gate the call behind a useEffect with [label] deps to avoid redundant publishes.`
+        );
+      }
+    },
+    [bridge, registered, id]
+  );
   const updateStyle = react.useCallback(
     (newStyle, newStateStyles) => {
       if (!bridge || !registered) return;
@@ -5419,7 +5745,8 @@ function useUIElement(options) {
     register,
     unregister,
     registeredElement,
-    updateStyle
+    updateStyle,
+    updateLabel
   };
 }
 function useUIElementWithProps(options) {
@@ -5733,6 +6060,11 @@ var UI_BRIDGE_NATIVE_ROUTES = {
     path: "/ui-bridge/control/snapshot",
     description: "Get full bridge snapshot"
   },
+  PAGE_HEALTH: {
+    method: "POST",
+    path: "/ui-bridge/control/page-health",
+    description: "Holistic page health diagnostic: spatial coverage, layout regions, text signals, interactive readiness, anomalies + ASCII heatmap"
+  },
   // Workflows
   GET_WORKFLOWS: {
     method: "GET",