@anubhav-choubey/web-for-agents 0.1.0 → 0.3.0

package/dist/{chunk-ZYMNO5AO.js → chunk-T42S3WRV.js}

@@ -1,12 +1,21 @@
 import {
-  collapseWhitespace
-} from "./chunk-FEAKVNMG.js";
+  ACTION_NAME_RULE,
+  collapseWhitespace,
+  isValidActionName
+} from "./chunk-4STTPCBR.js";
 import {
+  ACTION_ATTR,
+  ACTION_DESCRIPTION_ATTR,
+  ACTION_DESTRUCTIVE_ATTR,
   CONTENT_ATTR,
   EXCLUDE_ATTR,
   HIDDEN_SELECTOR,
-  resolveUrl
-} from "./chunk-AZG5MLNG.js";
+  LINK_ACTION_SELECTOR,
+  WEBMCP_TOOLDESCRIPTION_ATTR,
+  WEBMCP_TOOLNAME_ATTR,
+  resolveUrl,
+  tryResolveUrl
+} from "./chunk-2Y3LLYEC.js";
 
 // src/shared/shortcut.ts
 var DEFAULT_SHORTCUT = "alt+shift+a";
@@ -37,6 +46,143 @@ function matchesShortcut(e, s) {
   return e.code === s.code && e.altKey === s.alt && e.shiftKey === s.shift && e.ctrlKey === s.ctrl && e.metaKey === s.meta;
 }
 
+// src/shared/markupActions.ts
+function markupActions(doc) {
+  const out = [];
+  doc.querySelectorAll(`[${ACTION_ATTR}]`).forEach((el) => {
+    const name = el.getAttribute(ACTION_ATTR)?.trim();
+    if (!name) return;
+    const link = el.matches(LINK_ACTION_SELECTOR);
+    out.push({
+      element: el,
+      name,
+      description: el.getAttribute(ACTION_DESCRIPTION_ATTR) || null,
+      kind: el.tagName === "FORM" ? "form" : link ? "link" : "click",
+      destructive: el.getAttribute(ACTION_DESTRUCTIVE_ATTR) === "true",
+      source: "markup",
+      ...link ? { href: el.getAttribute("href") ?? "" } : {}
+    });
+  });
+  doc.querySelectorAll(`form[${WEBMCP_TOOLNAME_ATTR}]`).forEach((el) => {
+    const name = el.getAttribute(WEBMCP_TOOLNAME_ATTR)?.trim();
+    if (!name) return;
+    out.push({
+      element: el,
+      name,
+      description: el.getAttribute(WEBMCP_TOOLDESCRIPTION_ATTR) || null,
+      kind: "form",
+      destructive: false,
+      source: "webmcp-declarative"
+    });
+  });
+  return out;
+}
+function markupLinks(doc) {
+  return markupActions(doc).flatMap(
+    (a) => a.kind === "link" ? [{ name: a.name, description: a.description, destructive: a.destructive, href: a.href ?? "" }] : []
+  );
+}
+var LINK_ACTION_PROTOCOLS = ["http:", "https:", "mailto:", "tel:"];
+function resolveLinkHref(href, pageUrl) {
+  const url = tryResolveUrl(href, pageUrl);
+  if (url === null) return { ok: false, reason: "its href is not a valid URL" };
+  const protocol = new URL(url).protocol;
+  if (!LINK_ACTION_PROTOCOLS.includes(protocol)) {
+    return { ok: false, reason: `${protocol} links are not allowed (only http(s), mailto: and tel:)` };
+  }
+  return { ok: true, href: url };
+}
+var INVALID_NAME_REASON = `invalid name (${ACTION_NAME_RULE})`;
+function firstPerName(...groups) {
+  const seen = /* @__PURE__ */ new Set();
+  return groups.flat().filter((a) => !seen.has(a.name) && !!seen.add(a.name));
+}
+function actionGroups(markup) {
+  return [markup.filter((a) => a.kind !== "link"), markup.filter((a) => a.kind === "link")];
+}
+function linkActions(links, opts, warn) {
+  const seen = new Set(opts.taken);
+  const out = [];
+  for (const link of links) {
+    if (seen.has(link.name)) continue;
+    seen.add(link.name);
+    if (!isValidActionName(link.name)) {
+      warn(`link action "${link.name}" on ${opts.page} skipped: ${INVALID_NAME_REASON}`);
+      continue;
+    }
+    const r = resolveLinkHref(link.href, opts.pageUrl);
+    if (!r.ok) {
+      warn(`link action "${link.name}" on ${opts.page} skipped: ${r.reason}`);
+      continue;
+    }
+    out.push({
+      name: link.name,
+      description: link.description?.trim() || link.name,
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      destructive: link.destructive,
+      readOnly: !link.destructive,
+      kind: "link",
+      href: r.href,
+      .../^https?:$/.test(new URL(r.href).protocol) ? { method: "GET" } : {}
+    });
+  }
+  return out;
+}
+
+// src/shared/content.ts
+var DEFAULT_CONTENT_SELECTOR = "main";
+var STRIP = `script, style, noscript, template, nav, [${EXCLUDE_ATTR}], ${HIDDEN_SELECTOR}`;
+var BODY_STRIP = "header, nav, footer, aside";
+function selectContentRegion(doc, opts = {}) {
+  const element = doc.createElement("div");
+  const take = (n) => opts.inPlace ? n : n.cloneNode(true);
+  let source;
+  const markers = Array.from(doc.querySelectorAll(`[${CONTENT_ATTR}]`)).filter(
+    (el) => !el.parentElement?.closest(`[${CONTENT_ATTR}]`)
+  );
+  let selected = null;
+  if (markers.length > 0) {
+    source = "marker";
+    for (const m of markers) element.appendChild(take(m));
+  } else {
+    try {
+      selected = doc.querySelector(opts.contentSelector ?? DEFAULT_CONTENT_SELECTOR);
+    } catch {
+      selected = null;
+    }
+    if (selected) {
+      source = "selector";
+      element.appendChild(take(selected));
+    } else {
+      source = "body";
+      for (const child of Array.from(doc.body?.childNodes ?? [])) {
+        element.appendChild(take(child));
+      }
+      for (const el of Array.from(element.querySelectorAll(BODY_STRIP))) el.remove();
+    }
+  }
+  for (const el of Array.from(element.querySelectorAll(STRIP))) el.remove();
+  return { element, source };
+}
+
+// src/shared/pageMeta.ts
+function readPageMeta(doc) {
+  const titleTag = (doc.title ?? "").trim();
+  const title = titleTag || (doc.querySelector("h1")?.textContent ?? "").trim();
+  const description = doc.querySelector('meta[name="description"]')?.getAttribute("content")?.trim() || null;
+  const robots = doc.querySelector('meta[name="robots"]')?.getAttribute("content") ?? null;
+  const canonical = doc.querySelector('link[rel~="canonical"]')?.getAttribute("href")?.trim() || null;
+  return {
+    title: title || null,
+    titleFromDocument: title !== "",
+    titleTag: titleTag !== "",
+    description,
+    robots,
+    noindex: /noindex/i.test(robots ?? ""),
+    canonical
+  };
+}
+
 // src/shared/markdown.ts
 import TurndownService from "turndown";
 import { gfm } from "turndown-plugin-gfm";
@@ -108,68 +254,21 @@ function buildPageMarkdown(title, contentHtml, pageUrl) {
 ${body}`.replace(/\n+$/, "\n");
 }
 
-// src/shared/content.ts
-var DEFAULT_CONTENT_SELECTOR = "main";
-var STRIP = `script, style, noscript, template, nav, [${EXCLUDE_ATTR}], ${HIDDEN_SELECTOR}`;
-var BODY_STRIP = "header, nav, footer, aside";
-function selectContentRegion(doc, opts = {}) {
-  const element = doc.createElement("div");
-  const take = (n) => opts.inPlace ? n : n.cloneNode(true);
-  let source;
-  const markers = Array.from(doc.querySelectorAll(`[${CONTENT_ATTR}]`)).filter(
-    (el) => !el.parentElement?.closest(`[${CONTENT_ATTR}]`)
-  );
-  let selected = null;
-  if (markers.length > 0) {
-    source = "marker";
-    for (const m of markers) element.appendChild(take(m));
-  } else {
-    try {
-      selected = doc.querySelector(opts.contentSelector ?? DEFAULT_CONTENT_SELECTOR);
-    } catch {
-      selected = null;
-    }
-    if (selected) {
-      source = "selector";
-      element.appendChild(take(selected));
-    } else {
-      source = "body";
-      for (const child of Array.from(doc.body?.childNodes ?? [])) {
-        element.appendChild(take(child));
-      }
-      for (const el of Array.from(element.querySelectorAll(BODY_STRIP))) el.remove();
-    }
-  }
-  for (const el of Array.from(element.querySelectorAll(STRIP))) el.remove();
-  return { element, source };
-}
-
-// src/shared/pageMeta.ts
-function readPageMeta(doc) {
-  const titleTag = (doc.title ?? "").trim();
-  const title = titleTag || (doc.querySelector("h1")?.textContent ?? "").trim();
-  const description = doc.querySelector('meta[name="description"]')?.getAttribute("content")?.trim() || null;
-  const robots = doc.querySelector('meta[name="robots"]')?.getAttribute("content") ?? null;
-  const canonical = doc.querySelector('link[rel~="canonical"]')?.getAttribute("href")?.trim() || null;
-  return {
-    title: title || null,
-    titleFromDocument: title !== "",
-    titleTag: titleTag !== "",
-    description,
-    robots,
-    noindex: /noindex/i.test(robots ?? ""),
-    canonical
-  };
-}
-
 export {
-  escapeMarkdownInline,
-  escapeLinkTarget,
-  buildPageMarkdown,
+  markupActions,
+  markupLinks,
+  resolveLinkHref,
+  INVALID_NAME_REASON,
+  firstPerName,
+  actionGroups,
+  linkActions,
   DEFAULT_CONTENT_SELECTOR,
   selectContentRegion,
   DEFAULT_SHORTCUT,
   parseShortcut,
   matchesShortcut,
-  readPageMeta
+  readPageMeta,
+  escapeMarkdownInline,
+  escapeLinkTarget,
+  buildPageMarkdown
 };

package/dist/cli.js

@@ -2,12 +2,12 @@ import {
   audit,
   formatText,
   runCli
-} from "./chunk-IF32TPGR.js";
-import "./chunk-CKXHTGGT.js";
-import "./chunk-LCVI2PRP.js";
-import "./chunk-LCLDQ3A3.js";
-import "./chunk-FEAKVNMG.js";
-import "./chunk-AZG5MLNG.js";
+} from "./chunk-357ATBMS.js";
+import "./chunk-CGIIB6AF.js";
+import "./chunk-L3AYWCSX.js";
+import "./chunk-MIVGE5TM.js";
+import "./chunk-4STTPCBR.js";
+import "./chunk-2Y3LLYEC.js";
 import "./chunk-JJN6FNJD.js";
 export {
   audit,

package/dist/{happyDom-XVDHYJDM.js → happyDom-ZEFNMD7B.js}

@@ -2,9 +2,9 @@ import {
   createHappyDomRenderer,
   syncHint,
   syncRefusalText
-} from "./chunk-HONWT6GK.js";
-import "./chunk-AZG5MLNG.js";
-import "./chunk-5TNG4QMP.js";
+} from "./chunk-K3B53RIO.js";
+import "./chunk-2Y3LLYEC.js";
+import "./chunk-PGZH33B5.js";
 import "./chunk-JJN6FNJD.js";
 export {
   createHappyDomRenderer,

package/dist/index.d.ts

@@ -60,12 +60,23 @@ type JsonLdNode = {
     "@type": string;
     [k: string]: unknown;
 };
+/** A single `@graph` document: one `@context`, many nodes. Built by `schema.graph`. */
+type JsonLdGraph = {
+    "@context": "https://schema.org";
+    "@graph": JsonLdNode[];
+};
 /** JSON-LD as a string that is safe inside a `<script>` element (`<`, `>`, `&`, U+2028 and U+2029 are escaped). */
-declare function serializeJsonLd(data: JsonLdNode | JsonLdNode[]): string;
+declare function serializeJsonLd(data: JsonLdNode | JsonLdNode[] | JsonLdGraph): string;
 type Author = {
     name: string;
     url?: string;
 };
+type Offer = {
+    price: number | string;
+    priceCurrency: string;
+    availability?: "InStock" | "OutOfStock" | "PreOrder";
+    url?: string;
+};
 /** Builders for typed schema.org JSON-LD nodes. Undefined fields are omitted. */
 declare const schema: {
     article(i: {
@@ -83,12 +94,7 @@ declare const schema: {
         image?: string | string[];
         sku?: string;
         brand?: string;
-        offers?: {
-            price: number | string;
-            priceCurrency: string;
-            availability?: "InStock" | "OutOfStock" | "PreOrder";
-            url?: string;
-        };
+        offers?: Offer;
     }): JsonLdNode;
     faqPage(items: Array<{
         question: string;
@@ -109,11 +115,64 @@ declare const schema: {
         url: string;
         searchUrlTemplate?: string;
     }): JsonLdNode;
+    person(i: {
+        name: string;
+        url?: string;
+        image?: string;
+        jobTitle?: string;
+        description?: string;
+        email?: string;
+        sameAs?: string[];
+        worksFor?: string | {
+            name: string;
+            url?: string;
+        };
+    }): JsonLdNode;
+    softwareApplication(i: {
+        name: string;
+        description?: string;
+        applicationCategory?: string;
+        operatingSystem?: string;
+        url?: string;
+        image?: string | string[];
+        offers?: Offer;
+        aggregateRating?: {
+            ratingValue: number | string;
+            ratingCount?: number;
+            reviewCount?: number;
+            bestRating?: number;
+        };
+        author?: Author;
+    }): JsonLdNode;
+    profilePage(i: {
+        mainEntity: JsonLdNode;
+        url?: string;
+        name?: string;
+        dateCreated?: string;
+        dateModified?: string;
+    }): JsonLdNode;
+    creativeWork(i: {
+        name: string;
+        description?: string;
+        url?: string;
+        image?: string | string[];
+        author?: Author;
+        dateCreated?: string;
+        keywords?: string | string[];
+    }): JsonLdNode;
+    webPage(i: {
+        name: string;
+        url: string;
+        description?: string;
+        breadcrumb?: JsonLdNode;
+    }): JsonLdNode;
+    /** One `@graph` document from several nodes; each node's own `@context` is dropped in favour of a single top-level one. */
+    graph(nodes: JsonLdNode[]): JsonLdGraph;
 };
 
 /** Renders a `<script type="application/ld+json">` with `data`, escaped for safe embedding in HTML. */
 declare function JsonLd({ data }: {
-    data: JsonLdNode | JsonLdNode[];
+    data: JsonLdNode | JsonLdNode[] | JsonLdGraph;
 }): react.JSX.Element;
 
 type MarkerProps = {
@@ -171,7 +230,8 @@ type JsonSchema = {
     required?: string[];
     additionalProperties?: boolean;
 };
-type ActionKind = "handler" | "form" | "click";
+/** "link": a plain `<a href>` an agent can open without JavaScript (see markupActions). */
+type ActionKind = "handler" | "form" | "click" | "link";
 interface AgentActionDescriptor {
     name: string;
     title?: string;
@@ -180,6 +240,10 @@ interface AgentActionDescriptor {
     destructive: boolean;
     readOnly: boolean;
     kind: ActionKind;
+    /** Link actions only: the absolute http(s), mailto: or tel: URL. */
+    href?: string;
+    /** Link actions with an http(s) href only: open it with a GET request. */
+    method?: "GET";
 }
 type AgentActionResult = {
     status: "ok";
@@ -254,6 +318,20 @@ declare function AgentForm<I = Record<string, unknown>, R = unknown>(props: {
 /** Props that describe a form field to agents. */
 declare function agentParam(description: string): AgentParamProps;
 
+interface AgentLinkSpec {
+    /** 1 to 128 characters of A-Z a-z 0-9 _ - . Unique per page. */
+    name: string;
+    description: string;
+    /** Marks a link with side effects (for example an unsubscribe URL); it is then not readOnly. */
+    destructive?: boolean;
+}
+/**
+ * Props that make a plain `<a href>` a link action: listed in agents.json with its absolute href,
+ * no JavaScript needed. Only http(s), mailto: and tel: hrefs are listed. Registers nothing and is
+ * not exposed through WebMCP; safe to call during SSR and prerendering.
+ */
+declare function agentLinkProps(spec: AgentLinkSpec): AgentHintProps;
+
 /** The actions currently exposed on the page, sorted by name. */
 declare function listAgentActions(): AgentActionDescriptor[];
 /** Runs an exposed action with `input`. Never throws; failures are reported in the result. */
@@ -266,5 +344,5 @@ declare function executeAgentAction(name: string, input: unknown, signal?: Abort
  */
 declare function refreshAgentActions(opts?: RefreshAgentActionsOptions): void;
 
-export { AgentForm, CONTENT_ATTR, ContentRegion, EXCLUDE_ATTR, ExcludeFromContent, JsonLd, PRERENDERED_ATTR, READY_GLOBAL, Seo, SeoProvider, agentParam, executeAgentAction, holdPrerender, hydrateApp, listAgentActions, refreshAgentActions, schema, serializeJsonLd, useAgentAction, useSeo };
-export type { AgentActionDescriptor, AgentActionResult, AgentActionSpec, AgentHintProps, AgentParamProps, HeadTag, JsonLdNode, JsonSchema, RefreshAgentActionsOptions, SeoDefaults, SeoProps, SeoProviderProps };
+export { AgentForm, CONTENT_ATTR, ContentRegion, EXCLUDE_ATTR, ExcludeFromContent, JsonLd, PRERENDERED_ATTR, READY_GLOBAL, Seo, SeoProvider, agentLinkProps, agentParam, executeAgentAction, holdPrerender, hydrateApp, listAgentActions, refreshAgentActions, schema, serializeJsonLd, useAgentAction, useSeo };
+export type { AgentActionDescriptor, AgentActionResult, AgentActionSpec, AgentHintProps, AgentLinkSpec, AgentParamProps, HeadTag, JsonLdGraph, JsonLdNode, JsonSchema, RefreshAgentActionsOptions, SeoDefaults, SeoProps, SeoProviderProps };