@rudra-js/a2ui 0.8.2 → 0.8.3

package/README.md

@@ -8,10 +8,10 @@ It is not a hosted platform, a visual or low-code app builder, or a workspace yo
 
 This package puts that block inside the interfaces an [A2UI](https://a2ui.org) agent builds. It
 adds one component, `RudraRecommendations`, to the catalog your A2UI renderer draws from. The agent
-places it and hints at what the shopper is looking at. Your server still picks the products and
-builds the block with `@rudra-js/core`, and the browser renders it with `@rudra-js/react`.
+places it and passes hints about what the shopper is looking at. Your server still picks the
+products and builds the block with `@rudra-js/core`. The browser renders it with `@rudra-js/react`.
 
-It works with version 0.9 of the A2UI protocol, through `@a2ui/react` and `@a2ui/web_core` 0.14.
+It works with version 0.9 of the A2UI protocol, using `@a2ui/react` and `@a2ui/web_core` 0.14.
 
 ## Install
 
@@ -19,28 +19,29 @@ It works with version 0.9 of the A2UI protocol, through `@a2ui/react` and `@a2ui
 npm install @rudra-js/a2ui@latest @rudra-js/core@latest @rudra-js/react@latest @rudra-js/attested@latest @a2ui/react@0.14 @a2ui/web_core@0.14 react react-dom
 ```
 
-Run the same command in a new app, in one that already uses rudra-js or A2UI, and to upgrade. If
-your app has `@rudra-js/anthropic`, add `@rudra-js/anthropic@latest` to the command. The
-`@rudra-js` packages are published together, and each one's peer ranges on the others start at its
-own version. For a bare name npm stays inside the range your `package.json` already has, so
-without `@latest` an app on an older core can get an `ERESOLVE`. `@0.14` is the `@a2ui` release
-this package works with. `react` and `react-dom` carry no version, so npm and pnpm keep a React 18
-app on 18.
+Use the same command to install and to upgrade, whether or not your app already uses rudra-js or A2UI.
+If your app has `@rudra-js/anthropic`, add `@rudra-js/anthropic@latest` to that command.
 
-Everything but zod is a peer dependency, so your app holds one copy of each. npm and pnpm add
-peers for you, but your code imports most of them itself, and pnpm lets it import only what your
-`package.json` names. Yarn doesn't add peers, so there you need the whole list. It does move a bare
-name to its latest version, so leave out `react` and `react-dom` if your app already has React. On
-pnpm, read [zod](#zod) first.
+The `@rudra-js` packages are released together. Each one's peer range for the others starts at its
+own version. For a package name with no version, npm stays inside the range your `package.json`
+already has. Without `@latest`, an app on an older core can get an `ERESOLVE` error. `react`
+and `react-dom` have no version, so npm and pnpm keep a React 18 app on 18.
 
-Keep `skipLibCheck: true`. Without it, A2UI's own declarations fail to typecheck: they need `"dom"`
-in `lib`, and two of their imports have no file extension, which `nodenext` refuses.
+Everything except zod is a peer dependency, so your app holds one copy of each. npm and pnpm
+install peers for you. List them anyway, because your code imports most of them itself.
+pnpm only lets your code import what your `package.json` names. Yarn doesn't install peers, so on Yarn you
+need the whole list. Yarn also moves a name with no version to its latest release. So on Yarn, if your app
+already has React, leave out `react` and `react-dom`. On pnpm, read [zod](#zod) first.
+
+Keep `skipLibCheck: true` in your `tsconfig.json`. Without it, A2UI's own type declarations fail
+to typecheck. They need `"dom"` in `lib`. Two of their imports also have no file extension, which
+`nodenext` refuses.
 
 ## Three pieces
 
 ### The catalog your agent is prompted with
 
-Put `agentCatalog.toJson()` in your agent's prompt and have it create surfaces with
+Put `agentCatalog.toJson()` in your agent's prompt. Have the agent create surfaces with
 `catalogId: agentCatalog.id`. If you have catalog instructions of your own, join them to
 `RUDRA_RECOMMENDATIONS_INSTRUCTIONS`.
 
@@ -58,13 +59,16 @@ export const agentCatalog = new Catalog(
 );
 ```
 
-The first `toJson()` logs one "Recursive reference detected" warning per hint. It's harmless.
+The first `toJson()` call logs one "Recursive reference detected" warning per hint. It's harmless.
 
 ### Your endpoint
 
-`shopperFor` and `candidatesFor` stand for the session and catalog code you already have.
-`provider: null` calls no model, so pass your own provider. In the default cohort mode the model
-never sees `searchQuery`, so the agent's search only counts with `generation: 'per-shopper'`.
+`shopperFor` and `candidatesFor` stand in for the session and catalog code you already have.
+`provider: null` calls no model, so pass your own provider.
+
+`generation` defaults to `'cohort'`, which shares one block design between shoppers who look alike. In
+that mode the model never sees `searchQuery`. The agent's search only matters with
+`generation: 'per-shopper'`.
 
 ```ts
 import { createComponentGenerator, parseTrackingInput } from '@rudra-js/core';
@@ -103,11 +107,12 @@ export async function POST(request: Request): Promise<Response> {
 ```
 
 - `parseRecommendationRequest` accepts only `currentSku`, `currentCategory`, `searchQuery` and
-  `maxItems`. Anything else is a 400.
-- `fitRecommendationRequest` drops a SKU or category none of your candidates has.
-- Pick candidates on your side, not from the hints. Each new category, `maxItems` or candidate set
-  is a new model call, and with `per-shopper` so is each shopper and each new SKU or search, so
-  rate-limit the endpoint (see [SECURITY.md](https://github.com/clivedsouza1010/rudra-js/blob/main/SECURITY.md)).
+  `maxItems`. Anything else gets a 400.
+- `fitRecommendationRequest` drops a SKU or category that none of your candidates has.
+- Pick candidates on your side, not from the hints.
+- Each new category, `maxItems` or candidate set means a new model call. With `per-shopper`, so
+  does each shopper and each new SKU or search. Rate-limit the endpoint (see
+  [SECURITY.md](https://github.com/clivedsouza1010/rudra-js/blob/main/SECURITY.md)).
 - Send back `input.candidates` and `input.bundles`, not your raw catalog.
 
 ### The browser
@@ -142,51 +147,56 @@ const shopCatalog = new Catalog<ReactCatalogComponent>(
 export const processor = new MessageProcessor<ReactCatalogComponent>([shopCatalog]);
 ```
 
-Give the browser catalog the same id as the agent catalog, because A2UI looks it up by the
-`catalogId` the agent sends. Render the processor's surfaces with `A2uiSurface`. The options take
-`loadRecommendations`, `placeholder`, `onError`, and every `RudraComponent` prop except `spec`,
-`products` and `bundles`.
+Give the browser catalog the same id as the agent catalog. A2UI looks it up by the `catalogId` the
+agent sends. Render the processor's surfaces with `A2uiSurface`.
+
+`createRudraRecommendationsComponent` takes `loadRecommendations`, `placeholder` and `onError`. It
+also takes every `RudraComponent` prop except `spec`, `products` and `bundles`.
 
 ## What the component does
 
-- It reads each hint as a literal or from the agent's data model (`{ "path": "/viewing/sku" }`),
-  and sends only the four. It leaves out a blank one, and one the server would turn away, like a
-  `maxItems` of 40. A literal of the wrong type, like a numeric SKU, makes A2UI refuse the agent's
-  whole message.
-- It asks once the hints hold still for 300 ms, and keeps the last block up until the next one
-  arrives. `signal` aborts when the hints change or the component unmounts.
-- It checks the result against core's schemas before rendering any of it.
-- It shows `placeholder` until the first load. On a failed load, a bad result or a render error it
-  shows nothing and calls `onError`.
+- It reads each hint either as a literal value or from the agent's data model, like
+  `{ "path": "/viewing/sku" }`. It sends only the four hints the endpoint accepts.
+- It leaves out a hint that is blank, or one the server would turn away, like a `maxItems` of 40.
+- A literal of the wrong type, like a numeric SKU, makes A2UI refuse the agent's whole message.
+- It waits until the hints stop changing for 300 ms, then calls `loadRecommendations`.
+- It keeps showing the last block until the next one arrives.
+- `signal` aborts when the hints change or the component unmounts.
+- It checks the result against core's schemas before it renders any of it.
+- It shows `placeholder` until the first load finishes.
+- If a load fails or the result fails the schema check, it shows nothing and calls `onError`. It
+  does the same if the block throws while rendering.
 - Each component on a surface sends its own request.
 
 ## Where it runs
 
-`@rudra-js/a2ui` holds `createRudraRecommendationsComponent` and its types, and loads only in the
+`@rudra-js/a2ui` holds `createRudraRecommendationsComponent` and its types. It loads only in the
 browser, because `@a2ui/react` needs a DOM. The agent catalog and your endpoint import from
-`@rudra-js/a2ui/server`, which runs anywhere. In Next.js a `'use client'` file still runs on the
-server for the first render, so load the one that imports `@rudra-js/a2ui` from a client component
-with `next/dynamic` and `ssr: false`.
+`@rudra-js/a2ui/server`, which runs anywhere.
+
+In Next.js, a `'use client'` file still runs on the server for the first render. Load the file
+that imports `@rudra-js/a2ui` through `next/dynamic` with `ssr: false`, and make that call from a
+client component.
 
-A2UI renders on the client, so a crawler won't see a block an agent places. For a product page,
+A2UI renders in the browser, so a crawler won't see a block an agent places. For a product page,
 render `RudraComponent` on the server, as the
 [`@rudra-js/react` README](https://github.com/clivedsouza1010/rudra-js/tree/main/packages/react)
 describes.
 
 ## zod
 
-A2UI's schemas are zod 3, so this package depends on zod 3 while the rest of rudra-js uses zod 4.
-npm installs both, each where its package finds it, and you don't need either one yourself.
+A2UI's schemas use zod 3, so this package depends on zod 3. The rest of rudra-js uses zod 4. npm
+installs both, each where its own package finds it. With npm, you don't need either one yourself.
 
-On pnpm, `@a2ui/react` gets core's zod 4 as its zod peer, and the browser example stops
-typechecking (TS2344). If your app has no zod of its own, add zod 3:
+On pnpm, `@a2ui/react` gets core's zod 4 as its zod peer. Then the browser example fails to
+typecheck with TS2344. If your app has no zod of its own, add zod 3:
 
 ```sh
 pnpm add zod@^3.25.76
 ```
 
-If your app uses zod 4, drop the peer from `@a2ui/react` in `.pnpmfile.cjs`, and pnpm gives it
-the zod 3 it depends on:
+If your app uses zod 4, remove the zod peer from `@a2ui/react` in `.pnpmfile.cjs`. pnpm then gives
+it the zod 3 it depends on:
 
 ```js
 module.exports = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rudra-js/a2ui",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "A2UI component for rudra-js: lets an A2UI agent place a product-recommendation block whose products, prices and wording come from your shop, not from the agent",
   "keywords": [
     "rudra-js",
@@ -62,19 +62,19 @@
   "peerDependencies": {
     "@a2ui/react": "^0.14.0",
     "@a2ui/web_core": "^0.14.0",
-    "@rudra-js/core": "^0.8.2",
-    "@rudra-js/react": "^0.8.2",
+    "@rudra-js/core": "^0.8.3",
+    "@rudra-js/react": "^0.8.3",
     "react": "^18.2.0 || ^19.0.0"
   },
   "devDependencies": {
     "@a2ui/react": "0.14.0",
     "@a2ui/web_core": "0.14.0",
-    "@rudra-js/core": "0.8.2",
-    "@rudra-js/react": "0.8.2",
+    "@rudra-js/core": "0.8.3",
+    "@rudra-js/react": "0.8.3",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "jsdom": "^27.4.0",
-    "react": "^19.3.0",
-    "react-dom": "^19.3.0"
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
   }
 }