@sightmap/sightmap 0.5.2 → 0.7.1

package/dist/index.d.ts

@@ -51,4 +51,119 @@ interface CanonicalizeOptions {
 }
 declare function canonicalize(input: string, opts: CanonicalizeOptions): CanonicalizeResult;
 
-export { type CanonicalizeOptions, type CanonicalizeResult, Diagnostic, type FormatInput, Sightmap, ValidateResult, canonicalize, format, lint, loadDirectory, validate };
+interface BoundingRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * What an engine adapter's in-page evaluate returns for each sightmap
+ * component. matchCount is the number of DOM elements matched (after
+ * dedup); samplePosition is the bounding rect of the first match.
+ *
+ * Engine adapters produce this shape from their own browser-evaluate
+ * mechanism; the kernel does not care how.
+ */
+interface InPageSightmapMatch {
+    name: string;
+    selector: string[];
+    matchCount: number;
+    samplePosition?: BoundingRect | undefined;
+}
+interface EnrichSnapshotInput {
+    sightmap: Sightmap;
+    currentUrl: string;
+    inPageMatches: InPageSightmapMatch[];
+}
+interface SightmapSnapshotComponent {
+    name: string;
+    selector: string[];
+    memory: string[];
+    scope: "global" | "view-scoped";
+    matchCount: number;
+    samplePosition?: BoundingRect | undefined;
+}
+interface EnrichedSnapshot {
+    view: {
+        name: string;
+        route: string;
+        memory: string[];
+    } | null;
+    components: SightmapSnapshotComponent[];
+    memory: string[];
+}
+/**
+ * Pure function: combines a sightmap, the agent's current URL, and the
+ * in-page sightmap match results into an engine-agnostic enriched snapshot.
+ *
+ * Engine adapters typically wrap this and add their own passthrough fields
+ * (e.g. @sightmap/mcp adds ariaSnapshot for the Playwright MCP a11y text).
+ * The kernel never touches engine-specific text formats.
+ */
+declare function enrichSnapshot(input: EnrichSnapshotInput): EnrichedSnapshot;
+
+interface ResolveSightmapActInput {
+    componentName: string;
+}
+type ResolveSightmapActResult = {
+    kind: "ok";
+    componentName: string;
+    selector: string;
+    allSelectors: string[];
+} | {
+    kind: "error";
+    message: string;
+};
+/**
+ * Resolve a sightmap component by name to a CSS selector that an engine
+ * adapter's action verb (click/type/hover/...) can use as the target.
+ *
+ * Lookup order:
+ *   1. Global components (sightmap.globalComponents)
+ *   2. View-scoped components, walking each view's components list
+ *
+ * The first selector in the matching component's selector array is
+ * returned; additional selectors are exposed in allSelectors so callers
+ * can fall back if the engine's first-selector resolution fails.
+ */
+declare function resolveSightmapAct(sightmap: Sightmap, input: ResolveSightmapActInput): ResolveSightmapActResult;
+
+interface ParsedNetworkRequest {
+    method: string;
+    url: string;
+    status: number;
+    statusText: string;
+}
+interface AnnotatedNetworkRequest extends ParsedNetworkRequest {
+    sightmapName?: string;
+    sightmapMemory?: string[];
+}
+/**
+ * Cross-reference each captured network request with sightmap's `requests:`
+ * declarations. When a match is found, attaches the sightmap name + memory
+ * to the response. Unmatched requests are returned unchanged.
+ *
+ * The `requests` input is already normalized; this function does not parse
+ * any engine-specific text format. Engine adapters do their own parsing.
+ */
+declare function annotateNetworkRequests(sightmap: Sightmap, requests: ParsedNetworkRequest[]): AnnotatedNetworkRequest[];
+
+/**
+ * Build the in-page evaluate function body. Embeds the component selectors
+ * inline; the page only needs to query the DOM. No sightmap-js dependency
+ * in the page context.
+ *
+ * Engine adapters serialize this string and pass it to their browser's
+ * `evaluate` primitive (Playwright MCP's `browser_evaluate`, Playwright
+ * CLI's `playwright-cli eval`, etc.). The output shape is
+ * `{ url: string, matches: InPageSightmapMatch[] }` — adapters do their
+ * own parsing of the engine's wrapping (e.g. Playwright MCP's
+ * `### Result` framing).
+ */
+declare function buildInPageEvalFunction(components: Array<{
+    name: string;
+    selector: string[];
+}>): string;
+
+export { type AnnotatedNetworkRequest, type BoundingRect, type CanonicalizeOptions, type CanonicalizeResult, Diagnostic, type EnrichSnapshotInput, type EnrichedSnapshot, type FormatInput, type InPageSightmapMatch, type ParsedNetworkRequest, type ResolveSightmapActInput, type ResolveSightmapActResult, Sightmap, type SightmapSnapshotComponent, ValidateResult, annotateNetworkRequests, buildInPageEvalFunction, canonicalize, enrichSnapshot, format, lint, loadDirectory, resolveSightmapAct, validate };

package/dist/index.js

@@ -304,6 +304,17 @@ function splitSegments(path) {
   const trimmed = path.startsWith("/") ? path.slice(1) : path;
   return trimmed.split("/");
 }
+function routeSpecificity(route) {
+  if (route === "/") return 1;
+  let total = 0;
+  for (const seg of route.split("/")) {
+    if (seg === "" || seg === "**") continue;
+    if (seg === "*") total += 1;
+    else if (seg.startsWith(":")) total += 2;
+    else total += 3;
+  }
+  return total;
+}
 function matchSegs(pattern, url) {
   if (pattern.length === 0 && url.length === 0) return true;
   if (pattern.length === 0) return false;
@@ -326,10 +337,13 @@ function matchSegs(pattern, url) {
 // src/resolver.ts
 function resolveByUrl(sightmap, url, method) {
   let matchedView = null;
+  let bestScore = -1;
   for (const v of sightmap.views) {
-    if (routeMatch(v.route, url)) {
+    if (!routeMatch(v.route, url)) continue;
+    const score = routeSpecificity(v.route);
+    if (score > bestScore) {
+      bestScore = score;
       matchedView = v;
-      break;
     }
   }
   const components = [];
@@ -537,12 +551,12 @@ function routeShadowing(sightmap) {
   for (let j = 1; j < views.length; j++) {
     const later = views[j];
     const laterKey = matchSetKey(later.route);
-    const laterScore = specificity(later.route);
+    const laterScore = routeSpecificity(later.route);
     for (let i = 0; i < j; i++) {
       const earlier = views[i];
       if (earlier.route === later.route) continue;
       if (matchSetKey(earlier.route) !== laterKey) continue;
-      if (specificity(earlier.route) < laterScore) continue;
+      if (routeSpecificity(earlier.route) < laterScore) continue;
       out.push({
         severity: "warning",
         code: ROUTE_SHADOWING,
@@ -556,16 +570,6 @@ function routeShadowing(sightmap) {
 function matchSetKey(route) {
   return route.split("/").map((seg) => seg.startsWith(":") ? "*" : seg).join("/");
 }
-function specificity(route) {
-  let total = 0;
-  for (const seg of route.split("/")) {
-    if (seg === "" || seg === "**") continue;
-    if (seg === "*") total += 1;
-    else if (seg.startsWith(":")) total += 2;
-    else total += 3;
-  }
-  return total;
-}
 
 // src/lintRules/unknownSource.ts
 import { stat } from "fs/promises";
@@ -968,6 +972,122 @@ function serialize(doc) {
   });
   return out.endsWith("\n") ? out : out + "\n";
 }
+
+// src/enrich/snapshot.ts
+function enrichSnapshot(input) {
+  const { sightmap, currentUrl, inPageMatches } = input;
+  const result = match(sightmap, { url: currentUrl });
+  const inPageByName = /* @__PURE__ */ new Map();
+  for (const m of inPageMatches) inPageByName.set(m.name, m);
+  const components = result.components.map((c) => {
+    const inPage = inPageByName.get(c.name);
+    return {
+      name: c.name,
+      selector: c.selector,
+      memory: c.memory ?? [],
+      scope: c.scope,
+      matchCount: inPage?.matchCount ?? 0,
+      ...inPage?.samplePosition !== void 0 ? { samplePosition: inPage.samplePosition } : {}
+    };
+  });
+  return {
+    view: result.view ? {
+      name: result.view.name,
+      route: result.view.route,
+      memory: result.view.memory ?? []
+    } : null,
+    components,
+    memory: result.memory ?? []
+  };
+}
+
+// src/enrich/act.ts
+function resolveSightmapAct(sightmap, input) {
+  const found = findComponentByName(sightmap, input.componentName);
+  if (found === null) {
+    return {
+      kind: "error",
+      message: `Component "${input.componentName}" not found in the loaded sightmap.`
+    };
+  }
+  const selectors = Array.isArray(found.selector) ? found.selector : [];
+  if (selectors.length === 0) {
+    return {
+      kind: "error",
+      message: `Component "${input.componentName}" has no selector \u2014 cannot dispatch an action.`
+    };
+  }
+  return {
+    kind: "ok",
+    componentName: input.componentName,
+    selector: selectors[0],
+    allSelectors: selectors
+  };
+}
+function findComponentByName(sightmap, name) {
+  for (const c of sightmap.globalComponents) {
+    if (c.name === name) return c;
+  }
+  for (const v of sightmap.views) {
+    for (const c of v.components ?? []) {
+      if (c.name === name) return c;
+    }
+  }
+  return null;
+}
+
+// src/enrich/network.ts
+function annotateNetworkRequests(sightmap, requests) {
+  return requests.map((req) => {
+    const result = match(sightmap, { url: req.url, method: req.method });
+    const first = result.requests[0];
+    if (first === void 0) return req;
+    const annotated = { ...req, sightmapName: first.name };
+    if (first.memory && first.memory.length > 0) {
+      annotated.sightmapMemory = first.memory;
+    }
+    return annotated;
+  });
+}
+
+// src/enrich/in-page.ts
+function buildInPageEvalFunction(components) {
+  const componentsJson = JSON.stringify(components);
+  return `() => {
+    const components = ${componentsJson};
+    const matches = components.map((c) => {
+      const selectors = c.selector || [];
+      const seen = new Set();
+      const elements = [];
+      for (const sel of selectors) {
+        try {
+          const found = document.querySelectorAll(sel);
+          for (const el of Array.from(found)) {
+            if (!seen.has(el)) {
+              seen.add(el);
+              elements.push(el);
+            }
+          }
+        } catch {
+          // Invalid selector \u2014 skip silently.
+        }
+      }
+      const first = elements[0];
+      let samplePosition;
+      if (first && typeof first.getBoundingClientRect === "function") {
+        const r = first.getBoundingClientRect();
+        samplePosition = { x: r.x, y: r.y, width: r.width, height: r.height };
+      }
+      return {
+        name: c.name,
+        selector: selectors,
+        matchCount: elements.length,
+        samplePosition,
+      };
+    });
+    return { url: window.location.href, matches };
+  }`;
+}
 export {
   DUPLICATE_ROUTE,
   DUPLICATE_VIEW_NAME,
@@ -982,7 +1102,10 @@ export {
   SELECTOR_SYNTAX,
   UNKNOWN_SOURCE,
   UNKNOWN_VERSION,
+  annotateNetworkRequests,
+  buildInPageEvalFunction,
   canonicalize,
+  enrichSnapshot,
   explain,
   format,
   lint,
@@ -990,6 +1113,7 @@ export {
   match,
   merge,
   parse,
+  resolveSightmapAct,
   validate
 };
 //# sourceMappingURL=index.js.map