browserwire 0.1.0

package/cli/discovery/classify.js

@@ -0,0 +1,304 @@
+/**
+ * classify.js — Stage 3: Interactable Classification
+ *
+ * Runs on the CLI server. Takes raw ScannedElement[] + A11yInfo[] from
+ * Stages 1–2 and classifies which elements are interactable and what
+ * kind of interaction they afford.
+ *
+ * @typedef {{ scanId: number, interactionKind: string, confidence: number, inputType?: string }} InteractableElement
+ */
+
+// Input types that afford "type" interaction
+const TYPEABLE_INPUT_TYPES = new Set([
+  "text", "email", "password", "search", "tel", "url", "number", "date",
+  "datetime-local", "month", "time", "week", "color"
+]);
+
+// Input types that afford "toggle" interaction
+const TOGGLE_INPUT_TYPES = new Set(["checkbox", "radio"]);
+
+// Input types that afford "click" (button-like) interaction
+const BUTTON_INPUT_TYPES = new Set(["button", "reset", "image"]);
+
+// Roles that map to "click"
+const CLICK_ROLES = new Set(["button", "menuitem", "menuitemcheckbox", "menuitemradio", "tab", "treeitem"]);
+
+// Roles that map to "navigate"
+const NAVIGATE_ROLES = new Set(["link"]);
+
+// Roles that map to "type"
+const TYPE_ROLES = new Set(["textbox", "searchbox", "spinbutton"]);
+
+// Roles that map to "toggle"
+const TOGGLE_ROLES = new Set(["checkbox", "radio", "switch"]);
+
+// Roles that map to "select"
+const SELECT_ROLES = new Set(["combobox", "listbox"]);
+
+/**
+ * Classify a single element as interactable or not.
+ *
+ * @param {{ tagName: string, attributes: Record<string, string>, textContent: string }} element
+ * @param {{ role: string | null, name: string | null, isDisabled: boolean }} a11y
+ * @returns {InteractableElement | null} classification result, or null if not interactable
+ */
+const classifyElement = (element, a11y) => {
+  const tag = element.tagName;
+  const attrs = element.attributes;
+  const role = a11y?.role || null;
+  const isDisabled = a11y?.isDisabled || false;
+
+  // Disabled elements are still classified but with reduced confidence
+  const disabledPenalty = isDisabled ? 0.3 : 0;
+
+  // --- Tag-based classification (highest confidence) ---
+
+  // <button> or <summary> → click (unless type="submit")
+  if (tag === "button") {
+    const buttonType = (attrs.type || "").toLowerCase();
+    if (buttonType === "submit") {
+      return {
+        scanId: element.scanId,
+        interactionKind: "submit",
+        confidence: 0.95 - disabledPenalty
+      };
+    }
+    return {
+      scanId: element.scanId,
+      interactionKind: "click",
+      confidence: 0.95 - disabledPenalty
+    };
+  }
+
+  // <a> with href → navigate
+  if (tag === "a" && "href" in attrs) {
+    return {
+      scanId: element.scanId,
+      interactionKind: "navigate",
+      confidence: 0.95 - disabledPenalty
+    };
+  }
+
+  // <input> → depends on type
+  if (tag === "input") {
+    const inputType = (attrs.type || "text").toLowerCase();
+
+    if (inputType === "submit") {
+      return {
+        scanId: element.scanId,
+        interactionKind: "submit",
+        confidence: 0.95 - disabledPenalty,
+        inputType
+      };
+    }
+
+    if (TYPEABLE_INPUT_TYPES.has(inputType)) {
+      return {
+        scanId: element.scanId,
+        interactionKind: "type",
+        confidence: 0.95 - disabledPenalty,
+        inputType
+      };
+    }
+
+    if (TOGGLE_INPUT_TYPES.has(inputType)) {
+      return {
+        scanId: element.scanId,
+        interactionKind: "toggle",
+        confidence: 0.95 - disabledPenalty,
+        inputType
+      };
+    }
+
+    if (BUTTON_INPUT_TYPES.has(inputType)) {
+      return {
+        scanId: element.scanId,
+        interactionKind: "click",
+        confidence: 0.90 - disabledPenalty,
+        inputType
+      };
+    }
+
+    // Hidden, file, range — not standard interactables for our purposes
+    if (inputType === "hidden") {
+      return null;
+    }
+
+    if (inputType === "file") {
+      return {
+        scanId: element.scanId,
+        interactionKind: "click",
+        confidence: 0.70 - disabledPenalty,
+        inputType
+      };
+    }
+
+    if (inputType === "range") {
+      return {
+        scanId: element.scanId,
+        interactionKind: "click",
+        confidence: 0.70 - disabledPenalty,
+        inputType: "range"
+      };
+    }
+
+    // Fallback for unknown input types
+    return {
+      scanId: element.scanId,
+      interactionKind: "type",
+      confidence: 0.50 - disabledPenalty,
+      inputType
+    };
+  }
+
+  // <textarea> → type
+  if (tag === "textarea") {
+    return {
+      scanId: element.scanId,
+      interactionKind: "type",
+      confidence: 0.95 - disabledPenalty
+    };
+  }
+
+  // <select> → select
+  if (tag === "select") {
+    return {
+      scanId: element.scanId,
+      interactionKind: "select",
+      confidence: 0.95 - disabledPenalty
+    };
+  }
+
+  // <details> / <summary> → toggle
+  if (tag === "details" || tag === "summary") {
+    return {
+      scanId: element.scanId,
+      interactionKind: "toggle",
+      confidence: 0.85 - disabledPenalty
+    };
+  }
+
+  // --- Role-based classification (slightly lower confidence than tag-based) ---
+
+  if (role) {
+    if (role === "button" && tag !== "button") {
+      return {
+        scanId: element.scanId,
+        interactionKind: "click",
+        confidence: 0.85 - disabledPenalty
+      };
+    }
+
+    if (NAVIGATE_ROLES.has(role) && tag !== "a") {
+      return {
+        scanId: element.scanId,
+        interactionKind: "navigate",
+        confidence: 0.80 - disabledPenalty
+      };
+    }
+
+    if (TYPE_ROLES.has(role) && tag !== "input" && tag !== "textarea") {
+      return {
+        scanId: element.scanId,
+        interactionKind: "type",
+        confidence: 0.80 - disabledPenalty
+      };
+    }
+
+    if (TOGGLE_ROLES.has(role) && tag !== "input") {
+      return {
+        scanId: element.scanId,
+        interactionKind: "toggle",
+        confidence: 0.80 - disabledPenalty
+      };
+    }
+
+    if (SELECT_ROLES.has(role) && tag !== "select") {
+      return {
+        scanId: element.scanId,
+        interactionKind: "select",
+        confidence: 0.75 - disabledPenalty
+      };
+    }
+
+    if (CLICK_ROLES.has(role)) {
+      return {
+        scanId: element.scanId,
+        interactionKind: "click",
+        confidence: 0.80 - disabledPenalty
+      };
+    }
+  }
+
+  // --- Attribute-based classification (lower confidence) ---
+
+  // contenteditable → type
+  if (attrs.contenteditable === "true" || attrs.contenteditable === "") {
+    return {
+      scanId: element.scanId,
+      interactionKind: "type",
+      confidence: 0.75 - disabledPenalty
+    };
+  }
+
+  // onclick attribute → click
+  if ("onclick" in attrs) {
+    return {
+      scanId: element.scanId,
+      interactionKind: "click",
+      confidence: 0.60 - disabledPenalty
+    };
+  }
+
+  // tabindex (non-negative) on a non-interactive element suggests interactability
+  if ("tabindex" in attrs && tag !== "div" && tag !== "span") {
+    const tabindex = parseInt(attrs.tabindex, 10);
+    if (!isNaN(tabindex) && tabindex >= 0) {
+      return {
+        scanId: element.scanId,
+        interactionKind: "click",
+        confidence: 0.40 - disabledPenalty
+      };
+    }
+  }
+
+  // Not interactable
+  return null;
+};
+
+/**
+ * Classify all elements in a snapshot.
+ *
+ * @param {Array} elements - ScannedElement[] from Stage 1
+ * @param {Array} a11yEntries - A11yInfo[] from Stage 2
+ * @returns {{ interactables: InteractableElement[], stats: { total: number, interactable: number, byKind: Record<string, number> } }}
+ */
+export const classifyInteractables = (elements, a11yEntries) => {
+  // Build a11y lookup by scanId
+  const a11yMap = new Map();
+  for (const entry of a11yEntries) {
+    a11yMap.set(entry.scanId, entry);
+  }
+
+  const interactables = [];
+  const byKind = {};
+
+  for (const element of elements) {
+    const a11y = a11yMap.get(element.scanId) || null;
+    const result = classifyElement(element, a11y);
+
+    if (result && result.confidence > 0) {
+      interactables.push(result);
+      byKind[result.interactionKind] = (byKind[result.interactionKind] || 0) + 1;
+    }
+  }
+
+  return {
+    interactables,
+    stats: {
+      total: elements.length,
+      interactable: interactables.length,
+      byKind
+    }
+  };
+};

package/cli/discovery/compile.js

@@ -0,0 +1,392 @@
+/**
+ * compile.js — Stage 6: Manifest Draft Compilation
+ *
+ * Runs on the CLI server. Assembles outputs of Stages 3–5 into a draft
+ * BrowserWireManifest conforming to the M0 contract-dsl schema.
+ *
+ * @typedef {import('../../src/contract-dsl/types').BrowserWireManifest} BrowserWireManifest
+ */
+
+import { createHash } from "node:crypto";
+
+const CONTRACT_VERSION = "1.0.0";
+const MANIFEST_VERSION = "0.1.0";
+const RECIPE_REF = "recipe://static-discovery/v1";
+
+// ---------------------------------------------------------------------------
+// Standard error definitions
+// ---------------------------------------------------------------------------
+
+const STANDARD_ERRORS = [
+  {
+    code: "ERR_TARGET_NOT_FOUND",
+    messageTemplate: "Locator matched no elements on the page",
+    classification: "recoverable"
+  },
+  {
+    code: "ERR_TARGET_AMBIGUOUS",
+    messageTemplate: "Locator matched multiple elements (expected exactly one)",
+    classification: "recoverable"
+  },
+  {
+    code: "ERR_TARGET_DISABLED",
+    messageTemplate: "Target element exists but is currently disabled",
+    classification: "recoverable"
+  },
+  {
+    code: "ERR_ACTION_TIMEOUT",
+    messageTemplate: "Action did not complete within the allowed time",
+    classification: "fatal"
+  },
+  {
+    code: "ERR_PRECONDITION_FAILED",
+    messageTemplate: "Action precondition not met",
+    classification: "recoverable"
+  }
+];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a stable manifest ID from url.
+ */
+const deriveManifestId = (url) => {
+  try {
+    const parsed = new URL(url);
+    const pathHash = createHash("sha256")
+      .update(parsed.pathname + parsed.search)
+      .digest("hex")
+      .slice(0, 8);
+    return `manifest_${parsed.hostname.replace(/\./g, "_")}_${pathHash}`;
+  } catch {
+    return `manifest_${createHash("sha256").update(url).digest("hex").slice(0, 12)}`;
+  }
+};
+
+/**
+ * Derive site from URL origin.
+ */
+const deriveSite = (url) => {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return url;
+  }
+};
+
+/**
+ * Slugify a name for use as an ID segment.
+ */
+const slugify = (name) => {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 40) || "unnamed";
+};
+
+/**
+ * Map InteractionKind to a human-readable action name prefix.
+ */
+const interactionVerb = (kind) => {
+  const verbs = {
+    click: "Click",
+    type: "Type into",
+    select: "Select from",
+    toggle: "Toggle",
+    navigate: "Navigate to",
+    submit: "Submit",
+    scroll: "Scroll"
+  };
+  return verbs[kind] || "Interact with";
+};
+
+/**
+ * Map InteractionKind to confidence level string.
+ */
+const confidenceLevel = (score) => {
+  if (score >= 0.8) return "high";
+  if (score >= 0.5) return "medium";
+  return "low";
+};
+
+/**
+ * Build a LocatorSetDef from a LocatorCandidate's strategies.
+ */
+const buildLocatorSet = (locatorCandidate, actionId) => {
+  return {
+    id: `loc_${actionId}`,
+    strategies: locatorCandidate.strategies.map((s) => ({
+      kind: s.kind,
+      value: s.value,
+      confidence: s.confidence
+    }))
+  };
+};
+
+/**
+ * Generate action inputs for "type" and "select" interactions.
+ */
+const generateInputs = (interactable, element, a11yEntry) => {
+  const inputs = [];
+
+  if (interactable.interactionKind === "type") {
+    const inputType = interactable.inputType || "text";
+    const label = a11yEntry?.name || element?.attributes?.placeholder || "field";
+
+    let type = "string";
+    if (inputType === "number" || inputType === "range") {
+      type = "number";
+    }
+
+    inputs.push({
+      name: "text",
+      type,
+      required: a11yEntry?.isRequired || false,
+      description: `Value to type into ${label}`
+    });
+  }
+
+  if (interactable.interactionKind === "select") {
+    inputs.push({
+      name: "value",
+      type: "string",
+      required: true,
+      description: "Option to select"
+    });
+  }
+
+  return inputs;
+};
+
+/**
+ * Build provenance for a discovered item.
+ */
+const buildProvenance = (capturedAt, sessionId) => ({
+  source: "agent",
+  sessionId: sessionId || "static-discovery",
+  traceIds: [],
+  annotationIds: [],
+  capturedAt: capturedAt || new Date().toISOString()
+});
+
+// ---------------------------------------------------------------------------
+// Main compiler
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile stages 3–5 output into a draft BrowserWireManifest.
+ *
+ * @param {object} params
+ * @param {string} params.url - Page URL
+ * @param {string} params.title - Page title
+ * @param {string} params.capturedAt - ISO timestamp when the page was scanned
+ * @param {Array} params.elements - ScannedElement[]
+ * @param {Array} params.a11y - A11yInfo[]
+ * @param {Array} params.interactables - InteractableElement[]
+ * @param {Array} params.entities - EntityCandidate[]
+ * @param {Array} params.locators - LocatorCandidate[]
+ * @param {Array} [params.views] - ViewDef[] (pre-built from perception)
+ * @param {Array} [params.pages] - PageDef[] (pre-built from perception)
+ * @returns {{ manifest: BrowserWireManifest, stats: { entityCount: number, actionCount: number, errorCount: number, locatorSetCount: number } }}
+ */
+export const compileManifest = ({
+  url,
+  title,
+  capturedAt,
+  elements,
+  a11y,
+  interactables,
+  entities,
+  locators,
+  views,
+  pages
+}) => {
+  const sessionId = `discovery_${Date.now()}`;
+
+  // Build lookup maps
+  const elementMap = new Map();
+  for (const el of elements) {
+    elementMap.set(el.scanId, el);
+  }
+
+  const a11yMap = new Map();
+  for (const entry of a11y) {
+    a11yMap.set(entry.scanId, entry);
+  }
+
+  const locatorMap = new Map();
+  for (const loc of locators) {
+    locatorMap.set(loc.scanId, loc);
+  }
+
+  const interactableMap = new Map();
+  for (const item of interactables) {
+    interactableMap.set(item.scanId, item);
+  }
+
+  const provenance = buildProvenance(capturedAt, sessionId);
+
+  // --- Metadata ---
+  const metadata = {
+    id: deriveManifestId(url),
+    site: deriveSite(url),
+    createdAt: capturedAt || new Date().toISOString()
+  };
+
+  // --- Entities → EntityDef[] ---
+  const usedEntityIds = new Set();
+  const entityDefs = entities.map((candidate) => {
+    let entityId = `entity_${slugify(candidate.name)}`;
+    // Ensure uniqueness
+    if (usedEntityIds.has(entityId)) {
+      entityId = `${entityId}_${candidate.rootScanId}`;
+    }
+    usedEntityIds.add(entityId);
+
+    // Map signals to contract-dsl SignalDef format
+    const signals = candidate.signals.map((s) => ({
+      kind: s.kind,
+      value: s.value,
+      weight: Math.max(0, Math.min(1, s.weight))
+    }));
+
+    return {
+      id: entityId,
+      name: candidate.name,
+      description: `${candidate.source} entity discovered on ${title || url}`,
+      signals,
+      provenance,
+      // Store candidateId for action mapping
+      _candidateId: candidate.candidateId,
+      _memberScanIds: candidate.memberScanIds,
+      _interactableScanIds: candidate.interactableScanIds
+    };
+  });
+
+  // Build scanId → entityId reverse lookup
+  const scanIdToEntityId = new Map();
+  for (const entityDef of entityDefs) {
+    for (const sid of entityDef._interactableScanIds) {
+      // First entity wins (entities are priority-ordered)
+      if (!scanIdToEntityId.has(sid)) {
+        scanIdToEntityId.set(sid, entityDef.id);
+      }
+    }
+  }
+
+  // --- Actions → ActionDef[] ---
+  const usedActionIds = new Set();
+  const actionDefs = [];
+
+  for (const interactable of interactables) {
+    if (interactable.interactionKind === "none") continue;
+
+    const el = elementMap.get(interactable.scanId);
+    const a11yEntry = a11yMap.get(interactable.scanId);
+    const locatorCandidate = locatorMap.get(interactable.scanId);
+
+    if (!el || !locatorCandidate || locatorCandidate.strategies.length === 0) continue;
+
+    // Find entity this belongs to
+    const entityId = scanIdToEntityId.get(interactable.scanId) || null;
+
+    // Derive action name
+    const targetName = a11yEntry?.name?.trim().slice(0, 50) || el.textContent?.trim().slice(0, 50) || el.tagName;
+    const verb = interactionVerb(interactable.interactionKind);
+    const actionName = `${verb} ${targetName}`;
+
+    let actionId = `action_${slugify(actionName)}`;
+    if (usedActionIds.has(actionId)) {
+      actionId = `${actionId}_${interactable.scanId}`;
+    }
+    usedActionIds.add(actionId);
+
+    const inputs = generateInputs(interactable, el, a11yEntry);
+    const locatorSet = buildLocatorSet(locatorCandidate, actionId);
+
+    // Collect text content for LLM context
+    const textContent = (
+      a11yEntry?.name?.trim() ||
+      el.textContent?.trim() ||
+      ""
+    ).slice(0, 200);
+
+    // Only include if we have an entity to attach to
+    // If no entity found, create an orphan entity
+    let resolvedEntityId = entityId;
+    if (!resolvedEntityId) {
+      const orphanId = `entity_orphan_${interactable.scanId}`;
+      entityDefs.push({
+        id: orphanId,
+        name: targetName,
+        description: `Unscoped element discovered on ${title || url}`,
+        signals: [],
+        provenance,
+        _candidateId: null,
+        _memberScanIds: [interactable.scanId],
+        _interactableScanIds: [interactable.scanId]
+      });
+      usedEntityIds.add(orphanId);
+      resolvedEntityId = orphanId;
+    }
+
+    actionDefs.push({
+      id: actionId,
+      entityId: resolvedEntityId,
+      name: actionName,
+      interactionKind: interactable.interactionKind,
+      textContent: textContent || undefined,
+      inputs,
+      preconditions: [
+        { id: "pre_visible", description: "Target element is visible on the page" }
+      ],
+      postconditions: [
+        { id: "post_exists", description: "Action completed without error" }
+      ],
+      recipeRef: RECIPE_REF,
+      locatorSet,
+      errors: ["ERR_TARGET_NOT_FOUND", "ERR_TARGET_AMBIGUOUS"],
+      confidence: {
+        score: interactable.confidence,
+        level: confidenceLevel(interactable.confidence)
+      },
+      provenance
+    });
+  }
+
+  // Clean internal fields from entity defs
+  const cleanEntityDefs = entityDefs.map(({ _candidateId, _memberScanIds, _interactableScanIds, ...rest }) => rest);
+
+  // --- Assemble manifest ---
+  const manifest = {
+    contractVersion: CONTRACT_VERSION,
+    manifestVersion: MANIFEST_VERSION,
+    metadata,
+    entities: cleanEntityDefs,
+    actions: actionDefs,
+    errors: STANDARD_ERRORS
+  };
+
+  // Attach views and pages if provided
+  if (views && views.length > 0) {
+    manifest.views = views;
+  }
+  if (pages && pages.length > 0) {
+    manifest.pages = pages;
+  }
+
+  return {
+    manifest,
+    stats: {
+      entityCount: cleanEntityDefs.length,
+      actionCount: actionDefs.length,
+      errorCount: STANDARD_ERRORS.length,
+      locatorSetCount: actionDefs.length,
+      viewCount: views?.length || 0,
+      pageCount: pages?.length || 0
+    }
+  };
+};