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

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 };

package/dist/index.js

@@ -8,18 +8,20 @@ import {
   schemaFromForm,
   validateFormInput,
   validateInput
-} from "./chunk-LCVPXUFN.js";
+} from "./chunk-OKCYZE6C.js";
 import {
-  AGENT_GLOBAL_VERSION,
   DESCRIPTION_MAX_CHARS,
   DESCRIPTION_MIN_CHARS,
-  TITLE_MAX_CHARS,
-  isValidActionName
-} from "./chunk-PHTV5NAY.js";
+  TITLE_MAX_CHARS
+} from "./chunk-L3AYWCSX.js";
 import {
   compareStrings
 } from "./chunk-AAIYCJD3.js";
-import "./chunk-FEAKVNMG.js";
+import {
+  ACTION_NAME_RULE,
+  AGENT_GLOBAL_VERSION,
+  isValidActionName
+} from "./chunk-4STTPCBR.js";
 import {
   ACTION_ATTR,
   ACTION_DESCRIPTION_ATTR,
@@ -35,7 +37,7 @@ import {
   publicUrl,
   resolveUrl,
   routeOf
-} from "./chunk-F7PN5R25.js";
+} from "./chunk-2Y3LLYEC.js";
 import {
   errorMessage,
   withPrefix
@@ -338,6 +340,23 @@ function node(type, fields) {
   for (const [k, v] of Object.entries(fields)) if (v !== void 0) out[k] = v;
   return out;
 }
+function definedOnly(o) {
+  return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== void 0));
+}
+function nested(n) {
+  const { "@context": _context, ...rest } = n;
+  return rest;
+}
+function offer(o) {
+  if (o === void 0) return void 0;
+  return {
+    "@type": "Offer",
+    price: o.price,
+    priceCurrency: o.priceCurrency,
+    availability: o.availability && `https://schema.org/${o.availability}`,
+    url: o.url
+  };
+}
 var schema = {
   article(i) {
     const { author, ...rest } = i;
@@ -351,13 +370,7 @@ var schema = {
     return node("Product", {
       ...rest,
       brand: brand === void 0 ? void 0 : { "@type": "Brand", name: brand },
-      offers: offers === void 0 ? void 0 : {
-        "@type": "Offer",
-        price: offers.price,
-        priceCurrency: offers.priceCurrency,
-        availability: offers.availability && `https://schema.org/${offers.availability}`,
-        url: offers.url
-      }
+      offers: offer(offers)
     });
   },
   faqPage(items) {
@@ -392,6 +405,41 @@ var schema = {
         "query-input": "required name=search_term_string"
       } : void 0
     });
+  },
+  person(i) {
+    const { worksFor, ...rest } = i;
+    return node("Person", {
+      ...rest,
+      worksFor: worksFor === void 0 ? void 0 : typeof worksFor === "string" ? { "@type": "Organization", name: worksFor } : definedOnly({ "@type": "Organization", name: worksFor.name, url: worksFor.url })
+    });
+  },
+  softwareApplication(i) {
+    const { offers, aggregateRating, author, ...rest } = i;
+    return node("SoftwareApplication", {
+      ...rest,
+      offers: offer(offers),
+      aggregateRating: aggregateRating === void 0 ? void 0 : { "@type": "AggregateRating", ...definedOnly(aggregateRating) },
+      author: author === void 0 ? void 0 : person(author)
+    });
+  },
+  profilePage(i) {
+    return node("ProfilePage", { ...i, mainEntity: nested(i.mainEntity) });
+  },
+  creativeWork(i) {
+    const { author, keywords, ...rest } = i;
+    return node("CreativeWork", {
+      ...rest,
+      author: author === void 0 ? void 0 : person(author),
+      keywords: Array.isArray(keywords) ? keywords.join(", ") : keywords
+    });
+  },
+  webPage(i) {
+    const { breadcrumb, ...rest } = i;
+    return node("WebPage", { ...rest, breadcrumb: breadcrumb && nested(breadcrumb) });
+  },
+  /** One `@graph` document from several nodes; each node's own `@context` is dropped in favour of a single top-level one. */
+  graph(nodes) {
+    return { "@context": "https://schema.org", "@graph": nodes.map(nested) };
   }
 };
 
@@ -447,6 +495,11 @@ function hydrateApp(container, app, options) {
 // src/runtime/agent/react.tsx
 import { useCallback, useEffect as useEffect2, useLayoutEffect as useLayoutEffect2, useRef as useRef2 } from "react";
 
+// src/shared/actionName.ts
+function assertValidActionName(name) {
+  if (!isValidActionName(name)) throw new Error(withPrefix(`invalid action name "${name}": ${ACTION_NAME_RULE}`));
+}
+
 // src/runtime/agent/formAutomation.ts
 var MESSAGE_SELECTOR = '[role="alert"], [role="status"], [aria-live]';
 var MAX_MESSAGE = 500;
@@ -600,11 +653,6 @@ var nextId = 1;
 var syncScheduled = false;
 var forceScheduled = false;
 var CONFIRM_BUDGET = 1e3;
-function assertValidActionName(name) {
-  if (!isValidActionName(name)) {
-    throw new Error(withPrefix(`invalid action name "${name}": use 1-128 chars of A-Z a-z 0-9 _ - .`));
-  }
-}
 function installGlobal() {
   if (typeof window === "undefined") return;
   const w = window;
@@ -919,6 +967,18 @@ function AgentForm(props) {
 function agentParam(description) {
   return { [ACTION_PARAM_ATTR]: description };
 }
+
+// src/runtime/agent/link.ts
+function agentLinkProps(spec) {
+  assertValidActionName(spec.name);
+  const props = {
+    [ACTION_ATTR]: spec.name,
+    [ACTION_DESCRIPTION_ATTR]: spec.description,
+    "aria-description": spec.description
+  };
+  if (spec.destructive) props[ACTION_DESTRUCTIVE_ATTR] = "true";
+  return props;
+}
 export {
   AgentForm,
   CONTENT_ATTR,
@@ -930,6 +990,7 @@ export {
   READY_GLOBAL,
   Seo,
   SeoProvider,
+  agentLinkProps,
   agentParam,
   executeAgentAction,
   holdPrerender,

package/dist/overlay.js

@@ -1,25 +1,31 @@
 import {
   DEFAULT_CONTENT_SELECTOR,
   DEFAULT_SHORTCUT,
+  INVALID_NAME_REASON,
+  actionGroups,
   buildPageMarkdown,
+  firstPerName,
   markupActions,
   matchesShortcut,
   parseShortcut,
   readPageMeta,
+  resolveLinkHref,
   selectContentRegion
-} from "./chunk-PSNLS4GL.js";
+} from "./chunk-T42S3WRV.js";
 import {
   compareStrings
 } from "./chunk-AAIYCJD3.js";
 import {
   jsonLdTypes
-} from "./chunk-LCLDQ3A3.js";
-import "./chunk-FEAKVNMG.js";
+} from "./chunk-MIVGE5TM.js";
+import {
+  isValidActionName
+} from "./chunk-4STTPCBR.js";
 import {
   AGENT_GLOBAL,
   routeOf,
   trimTrailingSlash
-} from "./chunk-F7PN5R25.js";
+} from "./chunk-2Y3LLYEC.js";
 import {
   errorMessage
 } from "./chunk-JJN6FNJD.js";
@@ -63,18 +69,15 @@ function registryActions(doc) {
     return [];
   }
 }
-function collectActions(doc) {
-  const markup = markupActions(doc).map(
-    ({ name, description, kind, destructive, source }) => ({ name, description, kind, destructive, source })
-  );
-  const seen = /* @__PURE__ */ new Set();
-  const out = [];
-  for (const a of [...registryActions(doc), ...markup]) {
-    if (seen.has(a.name)) continue;
-    seen.add(a.name);
-    out.push(a);
-  }
-  return out.sort((a, b) => compareStrings(a.name, b.name));
+function collectActions(doc, pageUrl) {
+  const markup = markupActions(doc).map(({ name, description, kind, destructive, source, href }) => {
+    const a = { name, description, kind, destructive, source };
+    if (!isValidActionName(name)) return { ...a, warning: `Not listed in agents.json: ${INVALID_NAME_REASON}` };
+    if (kind !== "link") return a;
+    const r = resolveLinkHref(href ?? "", pageUrl);
+    return r.ok ? { ...a, href: r.href } : { ...a, warning: `Not listed in agents.json: ${r.reason}` };
+  });
+  return firstPerName(registryActions(doc), ...actionGroups(markup)).sort((a, b) => compareStrings(a.name, b.name));
 }
 function collectPageReport(doc = document, opts = {}) {
   const url = doc.location?.href ?? "";
@@ -110,7 +113,7 @@ function collectPageReport(doc = document, opts = {}) {
   } catch {
   }
   try {
-    actions = collectActions(doc);
+    actions = collectActions(doc, pageUrl);
   } catch {
   }
   return { url, meta, jsonLd, content, actions };
@@ -181,6 +184,8 @@ function renderPanel(root, report) {
     const line = [a.name, a.kind, a.source, a.destructive ? "destructive" : ""].filter(Boolean).join(" \xB7 ");
     actions.append(el(doc, "div", "action", el(doc, "strong", void 0, a.name), line.slice(a.name.length)));
     if (a.description) actions.append(el(doc, "div", "note", a.description));
+    if (a.href) actions.append(el(doc, "div", "note", a.href));
+    if (a.warning) actions.append(el(doc, "p", "warn", a.warning));
   }
   const refresh = el(doc, "button", "btn", "Refresh");
   refresh.setAttribute("type", "button");

package/dist/{renderChild-H6TR4SGV.js → renderChild-PSQLAIUW.js}

@@ -224,7 +224,7 @@ async function runRenderChild() {
   const allow = createAllowList();
   for (const o of [...options.localOrigins ?? [], ...options.allowOrigins ?? []]) allowOrigin(allow, o);
   containNetwork(allow);
-  const { createHappyDomRenderer } = await import("./happyDom-WTYQ5UAC.js");
+  const { createHappyDomRenderer } = await import("./happyDom-ZEFNMD7B.js");
   const renderer = createHappyDomRenderer(options);
   process.on("message", (m) => {
     if (m.type === "resources") {

package/dist/vite.d.ts

@@ -19,7 +19,7 @@ interface WebForAgentsOptions {
         disallow?: string[];
     };
     /** Generate sitemap.xml and the `Sitemap:` line in robots.txt. Default true. */
-    sitemap?: boolean;
+    sitemap?: boolean | SitemapOptions;
     /** Prerender routes after the build. `false` also turns off markdown, llms and the agent map. */
     prerender?: PrerenderOptions | false;
     /** Write a `.md` version of each page. `false` also turns off llms-full.txt. */
@@ -123,6 +123,33 @@ interface LlmsOptions {
     title?: string;
     /** llms.txt summary. Default: the description of "/". */
     description?: string;
+    /** Plain text after the summary, in llms.txt and llms-full.txt. Blank lines separate paragraphs. */
+    intro?: string;
+    /** Sections written before "## Pages" in llms.txt, and in the llms-full.txt header. */
+    sections?: LlmsSectionOptions[];
+}
+interface LlmsSectionOptions {
+    /** The section heading. */
+    title: string;
+    /** Plain text under the heading. Blank lines separate paragraphs. */
+    text?: string;
+    /** Links listed under the text. */
+    links?: LlmsLinkOptions[];
+}
+interface LlmsLinkOptions {
+    title: string;
+    /** http(s) or mailto: URL. A relative URL ("/resume.pdf") is resolved against siteUrl. */
+    url: string;
+    description?: string;
+}
+/** A route's last modification date: "YYYY-MM-DD", a W3C datetime, a Date, or undefined for none. */
+type SitemapLastmod = (route: string) => string | Date | undefined | Promise<string | Date | undefined>;
+interface SitemapOptions {
+    /**
+     * `<lastmod>` for each URL. "file": the source HTML file's modification time with `generate`, the
+     * build date with the plugin. A function returns the date per route. Default "none".
+     */
+    lastmod?: "file" | "none" | SitemapLastmod;
 }
 
 interface GenerateOptions {
@@ -135,7 +162,7 @@ interface GenerateOptions {
     /** Routes to leave out. A string is an exact path, or a prefix when it ends in "/*". */
     exclude?: Array<string | RegExp>;
     /** Write sitemap.xml and the `Sitemap:` line in robots.txt. Default true. */
-    sitemap?: boolean;
+    sitemap?: WebForAgentsOptions["sitemap"];
     /** Write a `.md` version of each page. `false` also turns off llms-full.txt. */
     markdown?: MarkdownOptions | false;
     /** Write llms.txt and llms-full.txt. Default on. */
@@ -191,4 +218,4 @@ declare const AI_BOTS: {
 declare function webForAgents(options: WebForAgentsOptions): Plugin[];
 
 export { AI_BOTS, generateAgentFiles, webForAgents };
-export type { AgentMapOptions, FileLayout, GenerateOptions, GenerateResult, GeneratedPage, LlmsOptions, MarkdownOptions, MarkdownTransform, MarkdownTransformPage, OverlayPluginOptions, PrerenderOptions, RendererName, Rule, WebForAgentsOptions };
+export type { AgentMapOptions, FileLayout, GenerateOptions, GenerateResult, GeneratedPage, LlmsLinkOptions, LlmsOptions, LlmsSectionOptions, MarkdownOptions, MarkdownTransform, MarkdownTransformPage, OverlayPluginOptions, PrerenderOptions, RendererName, Rule, SitemapLastmod, SitemapOptions, WebForAgentsOptions };