@rudra-js/a2ui 0.8.3 → 0.9.1

package/README.md

@@ -6,12 +6,15 @@ rudra-js is an open-source TypeScript library (MIT) you install from npm. A lang
 
 It is not a hosted platform, a visual or low-code app builder, or a workspace you sign up for.
 
-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 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`.
+You can use this package to put the block inside the interfaces an [A2UI](https://a2ui.org) agent
+builds. It adds a single component, `RudraRecommendations`, to the catalog your A2UI renderer draws
+from. This component will be placed by the agent, which will also pass hints about what the shopper
+is looking at. It's still up to your server to pick the products and build the block with
+`@rudra-js/core`. To render the block in the browser, this package uses `@rudra-js/react`. For
+Flutter, Angular or any other renderer, your server can send the block as A2UI messages instead (see
+[Flutter, Angular and other renderers](#flutter-angular-and-other-renderers)).
 
-It works with version 0.9 of the A2UI protocol, using `@a2ui/react` and `@a2ui/web_core` 0.14.
+It works with version 0.9 of the A2UI protocol and uses `@a2ui/react` and `@a2ui/web_core` 0.14.
 
 ## Install
 
@@ -19,29 +22,37 @@ It works with version 0.9 of the A2UI protocol, using `@a2ui/react` and `@a2ui/w
 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
 ```
 
-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.
-
-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.
-
-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.
+To install and also to upgrade, you will need to use this same command. It doesn't matter if your
+app already uses rudra-js or A2UI.
+Any app that has `@rudra-js/anthropic` will also need to add `@rudra-js/anthropic@latest` to this
+command.
+
+All the `@rudra-js` packages are released together. For each package, the peer range for the others
+starts at the version of that package. For a package name with no version, npm will stay inside the
+range your `package.json` already has. If `@latest` is left out, an app on an older core can get an
+`ERESOLVE` error. With no version on `react` and `react-dom`, npm and pnpm will keep a React 18 app
+on 18.
+
+Because everything except zod is a peer dependency, your app holds a single copy of each. On npm and
+pnpm, `@rudra-js/core`, `@rudra-js/attested` and `@a2ui/web_core` will be installed for you, but not
+`@a2ui/react`, `@rudra-js/react` or `react`. React can be left out on a server that only builds
+[messages for other renderers](#flutter-angular-and-other-renderers), since those three are
+optional. But those three have to stay in the command for the browser component to load. List the
+rest anyway, because your code imports most of these itself.
+With pnpm your code can only import the packages your `package.json` names. You will need the whole
+list on Yarn because it doesn't install peers. It will also move a name with no version to its
+latest release. So if your app already has React, leave out `react` and `react-dom` on Yarn. On
+pnpm, read [zod](#zod) first.
+
+A2UI's type declarations will fail to typecheck if you don't keep `skipLibCheck: true` in your
+`tsconfig.json`. They need `"dom"` in `lib`. Two of their imports will also be refused by `nodenext`
+because these have no file extension.
 
 ## Three pieces
 
 ### The catalog your agent is prompted with
 
-Put `agentCatalog.toJson()` in your agent's prompt. Have the agent create surfaces with
+Put `agentCatalog.toJson()` in your agent's prompt and have the agent create surfaces with
 `catalogId: agentCatalog.id`. If you have catalog instructions of your own, join them to
 `RUDRA_RECOMMENDATIONS_INSTRUCTIONS`.
 
@@ -59,15 +70,16 @@ export const agentCatalog = new Catalog(
 );
 ```
 
-The first `toJson()` call logs one "Recursive reference detected" warning per hint. It's harmless.
+You will see a "Recursive reference detected" warning per hint from the first `toJson()` call. It's
+harmless.
 
 ### Your endpoint
 
-`shopperFor` and `candidatesFor` stand in for the session and catalog code you already have.
-`provider: null` calls no model, so pass your own provider.
+`shopperFor` and `candidatesFor` stand in for the session and catalog code you already have. You
+will need to pass your own provider, because `provider: null` calls no model.
 
-`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
+By default `generation` is `'cohort'`. This shares a single block design between shoppers who look
+alike. In that mode the model never sees `searchQuery`. For the agent's search to matter, you need
 `generation: 'per-shopper'`.
 
 ```ts
@@ -107,13 +119,13 @@ export async function POST(request: Request): Promise<Response> {
 ```
 
 - `parseRecommendationRequest` accepts only `currentSku`, `currentCategory`, `searchQuery` and
-  `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.
+  `maxItems`. Anything else will get a 400.
+- `fitRecommendationRequest` will drop a SKU or category if it's not in any of your candidates.
+- Pick candidates on your side instead of from the hints.
+- There will be a new model call for each new category, `maxItems` or candidate set. With
+  `per-shopper` this also goes for 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` instead of your raw catalog.
 
 ### The browser
 
@@ -147,56 +159,129 @@ const shopCatalog = new Catalog<ReactCatalogComponent>(
 export const processor = new MessageProcessor<ReactCatalogComponent>([shopCatalog]);
 ```
 
-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`.
+Give the browser catalog the id of the agent catalog, because A2UI will look it up by the
+`catalogId` the agent sends. Use `A2uiSurface` to render the surfaces of the processor.
 
 `createRudraRecommendationsComponent` takes `loadRecommendations`, `placeholder` and `onError`. It
-also takes every `RudraComponent` prop except `spec`, `products` and `bundles`.
+also takes all of the `RudraComponent` props except `spec`, `products` and `bundles`.
 
 ## What the component does
 
-- 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 will read each hint either as a literal value or from the agent's data model, like
+  `{ "path": "/viewing/sku" }`. It will only send the four hints the endpoint accepts.
+- It leaves out any hint that is blank. It also leaves out a hint the server would turn away, like a
+  `maxItems` of 40.
+- With a literal of the wrong type, like a numeric SKU, A2UI will refuse the agent's whole message.
+- It waits for the hints to stop changing for 300 ms and 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 will check 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.
+- If a load fails or the result fails the schema check, it will show nothing and call `onError`.
+  This is also what happens 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. 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.
+`@rudra-js/a2ui` holds `createRudraRecommendationsComponent` and its types. It can only be loaded in
+the browser, because `@a2ui/react` needs a DOM. For the agent catalog and your endpoint, import from
+`@rudra-js/a2ui/server`. This entry point can run 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.
+In Next.js, a `'use client'` file will also run on the server for the first render. To load the file
+that imports `@rudra-js/a2ui`, you will need `next/dynamic` with `ssr: false`. This call has to be
+made from a client component.
 
-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
+Any block an agent places won't be seen by a crawler, because A2UI renders in the browser. 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.
 
+## Flutter, Angular and other renderers
+
+`RudraRecommendations` needs a React renderer. For any other A2UI renderer, build the block on your
+server as A2UI messages that use just the basic catalog. All renderers ship with this catalog. If
+your server has no React, it only needs these:
+
+```sh
+npm install @rudra-js/a2ui@latest @rudra-js/core@latest @rudra-js/attested@latest @a2ui/web_core@0.14
+```
+
+If your server has `@rudra-js/anthropic`, add `@rudra-js/anthropic@latest` to that command too.
+
+```ts
+import { buildRecommendationMessages, type RecommendationResult } from '@rudra-js/a2ui/server';
+
+export function messagesFor(result: RecommendationResult, locale: string) {
+  return buildRecommendationMessages(result, {
+    surfaceId: 'rudra_recommendations',
+    shopUrl: 'https://shop.example',
+    locale,
+  });
+}
+```
+
+In [your endpoint](#your-endpoint), return `Response.json(messagesFor(result, shopper.locale))`
+instead of `result`. Skip the [agent catalog](#the-catalog-your-agent-is-prompted-with) and
+[browser](#the-browser) pieces and keep `rudraRecommendationsApi` out of your agent's catalog,
+because they are all for `RudraRecommendations`, which needs React. Use your own `surfaceId` in
+place of `'rudra_recommendations'`. It must never be named in your agent's prompt.
+
+Your app can call the endpoint with the four hints and give the messages it gets back to its A2UI
+renderer. This is the safer way. Your agent's code can also call it and pass the messages on to the
+client unchanged, but then the call has to carry the shopper's session because `shopperFor` reads
+the shopper from the request. Either way, keep the model away from the messages and from the surface
+of the block, as [SECURITY.md](https://github.com/clivedsouza1010/rudra-js/blob/main/SECURITY.md)
+explains.
+
+- These messages will create the surface named `surfaceId` and then fill it. To show a new block
+  there, first send `deleteSurface` for this surface. You will get no messages if nothing in the
+  block can be shown.
+- Grids and carousels show two cards to a row, because the basic catalog can't fit cards to the
+  screen and its `List` doesn't scroll on all renderers.
+- Each product card is a button to open the product's page. By default `hrefForSku` builds the link
+  as `/product/<sku>`. `shopUrl` will resolve this link and any relative image URL, because a native
+  app has no page to resolve them against. If the image URL of a product is empty or only spaces, no
+  image will be shown. An empty link will throw. A link or an image that doesn't end up `http` or
+  `https` will also throw.
+- Featured cards look like any other card and banners look the same in all tones, because the basic
+  catalog has no styles for them. As nothing carries the `data-rudra-*` attributes the React block
+  uses for click tracking, you will need to add a query parameter in `hrefForSku` to count clicks.
+- Prices are formatted on your server for `locale`. If you leave it out, they will use the default
+  locale of the server and not the shopper's. You can also pass `formatPrice` and
+  `formatBundlePrice` to format prices yourself.
+- All text uses a heading or caption style and never body, because the web renderers only read body
+  text as Markdown. Flutter's `genui` and the A2UI SwiftUI renderer read all styles as Markdown, as
+  the
+  [A2UI guide](https://github.com/a2ui-project/a2ui/blob/main/specification/v0_9_1/docs/basic_catalog_implementation_guide.md)
+  asks. So square brackets become parentheses, while `<` and `>` become `‹` and `›`. Line breaks
+  also become spaces. No text can load an image. Only a bare web address or email address can show
+  as a link. On SwiftUI a tap will open the link, but on `genui` it does nothing and text that
+  starts with `#` or `-` followed by a space shows as Markdown.
+- Neither the rationale nor how the block was generated is ever sent.
+- Flutter's `genui` knows the basic catalog by its id from 0.10.3. For 0.8 to 0.10.2, pass
+  `catalogId: 'https://a2ui.org/specification/v0_9/basic_catalog.json'`. On Android 11 and later, a
+  tap on a card will do nothing if the app doesn't declare `https` links under `<queries>` in its
+  manifest.
+- On `@a2ui/angular` 0.13, register the `BasicCatalog` from `@a2ui/angular/v0_9` because the catalog
+  from `@a2ui/angular` has the v1.0 id. You also have to pass `useUniversalComponents: true` to
+  `provideA2Ui` next to `catalogs`. If you don't, a click on a card will do nothing and all cards
+  will try to open their links in a new tab as soon as they render.
+
 ## zod
 
-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.
+This package depends on zod 3 because A2UI's schemas use zod 3, but the rest of rudra-js uses zod 4.
+npm will install both, each where its own package can find it. With npm you don't need to add either
+version yourself.
 
-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:
+On pnpm, `@a2ui/react` gets core's zod 4 as its zod peer. This makes the browser example fail to
+typecheck with TS2344. If your app has no zod of its own, you will need to add zod 3:
 
 ```sh
 pnpm add zod@^3.25.76
 ```
 
-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:
+If your app uses zod 4, you will need to remove the zod peer from `@a2ui/react` in `.pnpmfile.cjs`.
+Then pnpm will give it the zod 3 it depends on:
 
 ```js
 module.exports = {

package/dist/recommendation-messages.d.ts

@@ -0,0 +1,14 @@
+import type { A2uiMessage } from '@a2ui/web_core/v0_9';
+import type { Bundle, Product } from '@rudra-js/core';
+import type { RecommendationResult } from './recommendation-result.js';
+export interface RecommendationMessagesOptions {
+    surfaceId: string;
+    shopUrl: string;
+    catalogId?: string | undefined;
+    hrefForSku?: ((sku: string) => string) | undefined;
+    formatPrice?: ((product: Product) => string) | undefined;
+    formatBundlePrice?: ((bundle: Bundle) => string) | undefined;
+    locale?: string | undefined;
+}
+export declare function buildRecommendationMessages(result: RecommendationResult, options: RecommendationMessagesOptions): A2uiMessage[];
+//# sourceMappingURL=recommendation-messages.d.ts.map

package/dist/recommendation-messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendation-messages.d.ts","sourceRoot":"","sources":["../src/recommendation-messages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAGV,MAAM,EAIN,OAAO,EAER,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAEvE,MAAM,WAAW,6BAA6B;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,UAAU,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,SAAS,CAAC;IACnD,WAAW,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,GAAG,SAAS,CAAC;IACzD,iBAAiB,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,SAAS,CAAC;IAC7D,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAuTD,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,6BAA6B,GACrC,WAAW,EAAE,CAoCf"}

package/dist/recommendation-messages.js

@@ -0,0 +1,242 @@
+const BASIC_CATALOG_ID = 'https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json';
+const CARDS_PER_ROW = 2;
+function defaultHrefForSku(sku) {
+    return `/product/${encodeURIComponent(sku)}`;
+}
+function formatMoney(price, currency, locale) {
+    let formatter;
+    try {
+        formatter = new Intl.NumberFormat(locale, { style: 'currency', currency });
+    }
+    catch {
+        return `${currency} ${price}`;
+    }
+    return formatter.format(price);
+}
+function defaultFormatPrice(product, locale) {
+    if (!Number.isFinite(product.price)) {
+        throw new TypeError(`price for SKU ${product.sku} is ${String(product.price)}, not a finite number. ` +
+            'Catalog objects must satisfy productSchema from @rudra-js/core');
+    }
+    return formatMoney(product.price, product.currency, locale);
+}
+function defaultFormatBundlePrice(bundle, locale) {
+    if (!Number.isFinite(bundle.price)) {
+        throw new TypeError(`price for bundle ${bundle.id} is ${String(bundle.price)}, not a finite number. ` +
+            'Bundle objects must satisfy bundleSchema from @rudra-js/core');
+    }
+    return formatMoney(bundle.price, bundle.currency, locale);
+}
+function toWebUrl(value, base, name) {
+    if (typeof value !== 'string')
+        throw new TypeError(`${name} is not a string`);
+    if (value.trim() === '')
+        throw new TypeError(`${name} is empty`);
+    let url;
+    try {
+        url = new URL(value, base);
+    }
+    catch {
+        throw new TypeError(`${name} is not a URL: ${value}`);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new TypeError(`${name} is not an http or https URL: ${value}`);
+    }
+    return url.href;
+}
+function plainText(value) {
+    return value
+        .replace(/[\t\n\v\f\r \u0085\u2028\u2029]+/g, ' ')
+        .trim()
+        .replaceAll('[', '(')
+        .replaceAll(']', ')')
+        .replaceAll('<', '‹')
+        .replaceAll('>', '›');
+}
+function defined(ids) {
+    return ids.filter((id) => id !== undefined);
+}
+function sellableProduct(context, sku) {
+    const product = context.products.get(sku);
+    return product?.isInStock === false ? undefined : product;
+}
+function addText(context, id, value, variant) {
+    const text = value === null ? '' : plainText(value);
+    return text ? context.add({ id, component: 'Text', text, variant }) : undefined;
+}
+function addStartColumn(context, id, children) {
+    return context.add({ id, component: 'Column', align: 'start', children: defined(children) });
+}
+function addColumn(context, id, children) {
+    return context.add({ id, component: 'Column', children: defined(children) });
+}
+function addLink(context, id, sku, child) {
+    const url = context.linkFor(sku);
+    return context.add({
+        id,
+        component: 'Button',
+        child,
+        variant: 'borderless',
+        action: { functionCall: { call: 'openUrl', args: { url }, returnType: 'void' } },
+    });
+}
+function addLinkedCard(context, id, sku, children, weight) {
+    const link = addLink(context, `${id}_link`, sku, addStartColumn(context, `${id}_body`, children));
+    return context.add({
+        id,
+        component: 'Card',
+        child: link,
+        ...(weight === undefined ? {} : { weight }),
+    });
+}
+function addProductCard(context, id, reference, product) {
+    const image = product.imageUrl?.trim()
+        ? context.add({
+            id: `${id}_image`,
+            component: 'Image',
+            url: toWebUrl(product.imageUrl, context.shopUrl, `the image for SKU ${product.sku}`),
+            fit: 'cover',
+            variant: 'mediumFeature',
+        })
+        : undefined;
+    return addLinkedCard(context, id, product.sku, [
+        image,
+        addText(context, `${id}_badge`, reference.badge, 'caption'),
+        addText(context, `${id}_title`, product.title, 'h5'),
+        addText(context, `${id}_price`, context.formatPrice(product), 'h5'),
+        addText(context, `${id}_reason`, reference.reason, 'caption'),
+    ], 1);
+}
+function addCardRows(context, id, title, items) {
+    const cards = [];
+    for (const reference of items) {
+        const product = sellableProduct(context, reference.sku);
+        if (product) {
+            cards.push(addProductCard(context, `${id}_item${cards.length}`, reference, product));
+        }
+    }
+    if (cards.length === 0)
+        return undefined;
+    const rows = [];
+    for (let start = 0; start < cards.length; start += CARDS_PER_ROW) {
+        const rowId = `${id}_row${rows.length}`;
+        const row = cards.slice(start, start + CARDS_PER_ROW);
+        while (row.length < CARDS_PER_ROW) {
+            row.push(context.add({
+                id: `${rowId}_space${row.length}`,
+                component: 'Column',
+                children: [],
+                weight: 1,
+            }));
+        }
+        rows.push(context.add({ id: rowId, component: 'Row', align: 'start', children: row }));
+    }
+    return addColumn(context, id, [addText(context, `${id}_title`, title, 'h3'), ...rows]);
+}
+function addHero(context, id, block) {
+    const product = block.sku === null ? undefined : sellableProduct(context, block.sku);
+    const headline = addText(context, `${id}_headline`, block.headline, 'h3');
+    const body = addText(context, `${id}_body`, block.body, 'caption');
+    if (!headline && !body && !product)
+        return undefined;
+    const card = product
+        ? addLinkedCard(context, `${id}_product`, product.sku, [
+            addText(context, `${id}_product_title`, product.title, 'h4'),
+            addText(context, `${id}_product_price`, context.formatPrice(product), 'h5'),
+            addText(context, `${id}_product_cta`, block.ctaLabel, 'h5'),
+        ], undefined)
+        : undefined;
+    return addStartColumn(context, id, [headline, body, card]);
+}
+function addBanner(context, id, block) {
+    const body = addStartColumn(context, `${id}_body`, [
+        addText(context, `${id}_text`, block.text, 'h5'),
+        addText(context, `${id}_cta`, block.ctaLabel, 'h5'),
+    ]);
+    return context.add({ id, component: 'Card', child: body });
+}
+function addCopy(context, id, block) {
+    return addStartColumn(context, id, [
+        addText(context, `${id}_title`, block.title, 'h3'),
+        addText(context, `${id}_body`, block.body, 'caption'),
+    ]);
+}
+function addBundle(context, id, block) {
+    const bundle = block.bundleId === null ? undefined : context.bundles.get(block.bundleId);
+    if (!bundle)
+        return undefined;
+    const products = [];
+    for (const sku of bundle.skus) {
+        const product = sellableProduct(context, sku);
+        if (!product)
+            return undefined;
+        products.push(product);
+    }
+    const items = addStartColumn(context, `${id}_items`, products.map((product, index) => addLink(context, `${id}_item${index}`, product.sku, context.add({
+        id: `${id}_item${index}_title`,
+        component: 'Text',
+        text: plainText(product.title) || plainText(product.sku),
+        variant: 'h5',
+    }))));
+    const body = addStartColumn(context, `${id}_body`, [
+        addText(context, `${id}_label`, bundle.label ?? null, 'h3'),
+        addText(context, `${id}_title`, block.title, 'h4'),
+        addText(context, `${id}_text`, block.body, 'caption'),
+        items,
+        addText(context, `${id}_price`, context.formatBundlePrice(bundle), 'h5'),
+        addText(context, `${id}_cta`, block.ctaLabel, 'h5'),
+    ]);
+    return context.add({ id, component: 'Card', child: body });
+}
+function addBlock(context, id, block) {
+    switch (block.kind) {
+        case 'hero':
+            return addHero(context, id, block);
+        case 'grid':
+        case 'carousel':
+            return addCardRows(context, id, block.title, block.items);
+        case 'banner':
+            return addBanner(context, id, block);
+        case 'copy':
+            return addCopy(context, id, block);
+        case 'bundle':
+            return addBundle(context, id, block);
+        default:
+            block;
+            return undefined;
+    }
+}
+export function buildRecommendationMessages(result, options) {
+    const shopUrl = toWebUrl(options.shopUrl, undefined, 'the shop URL');
+    const hrefForSku = options.hrefForSku ?? defaultHrefForSku;
+    const components = [];
+    const context = {
+        products: new Map(result.products.map((product) => [product.sku, product])),
+        bundles: new Map((result.bundles ?? []).map((bundle) => [bundle.id, bundle])),
+        shopUrl,
+        linkFor: (sku) => toWebUrl(hrefForSku(sku), shopUrl, `the link for SKU ${sku}`),
+        formatPrice: options.formatPrice ?? ((product) => defaultFormatPrice(product, options.locale)),
+        formatBundlePrice: options.formatBundlePrice ?? ((bundle) => defaultFormatBundlePrice(bundle, options.locale)),
+        add: (component) => {
+            components.push(component);
+            return component.id;
+        },
+    };
+    const blocks = defined(result.spec.blocks.map((block, index) => addBlock(context, `block${index}`, block)));
+    if (blocks.length === 0)
+        return [];
+    addColumn(context, 'root', [
+        addText(context, 'headline', result.spec.headline, 'h2'),
+        addText(context, 'subheadline', result.spec.subheadline, 'caption'),
+        ...blocks,
+    ]);
+    const { surfaceId } = options;
+    return [
+        {
+            version: 'v0.9',
+            createSurface: { surfaceId, catalogId: options.catalogId ?? BASIC_CATALOG_ID },
+        },
+        { version: 'v0.9', updateComponents: { surfaceId, components } },
+    ];
+}
+//# sourceMappingURL=recommendation-messages.js.map

package/dist/recommendation-messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendation-messages.js","sourceRoot":"","sources":["../src/recommendation-messages.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -1,4 +1,5 @@
 export { RUDRA_RECOMMENDATIONS_INSTRUCTIONS, rudraRecommendationsApi, } from './recommendations-api.js';
 export { fitRecommendationRequest, parseRecommendationRequest, type RecommendationRequest, } from './recommendation-request.js';
+export { buildRecommendationMessages, type RecommendationMessagesOptions, } from './recommendation-messages.js';
 export type { RecommendationResult } from './recommendation-result.js';
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kCAAkC,EAClC,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,KAAK,qBAAqB,GAC3B,MAAM,6BAA6B,CAAC;AAErC,YAAY,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kCAAkC,EAClC,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,KAAK,qBAAqB,GAC3B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,2BAA2B,EAC3B,KAAK,6BAA6B,GACnC,MAAM,8BAA8B,CAAC;AAEtC,YAAY,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/server.js

@@ -1,3 +1,4 @@
 export { RUDRA_RECOMMENDATIONS_INSTRUCTIONS, rudraRecommendationsApi, } from './recommendations-api.js';
 export { fitRecommendationRequest, parseRecommendationRequest, } from './recommendation-request.js';
+export { buildRecommendationMessages, } from './recommendation-messages.js';
 //# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kCAAkC,EAClC,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,wBAAwB,EACxB,0BAA0B,GAE3B,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kCAAkC,EAClC,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,wBAAwB,EACxB,0BAA0B,GAE3B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,2BAA2B,GAE5B,MAAM,8BAA8B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rudra-js/a2ui",
-  "version": "0.8.3",
+  "version": "0.9.1",
   "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,15 +62,26 @@
   "peerDependencies": {
     "@a2ui/react": "^0.14.0",
     "@a2ui/web_core": "^0.14.0",
-    "@rudra-js/core": "^0.8.3",
-    "@rudra-js/react": "^0.8.3",
+    "@rudra-js/core": "^0.9.1",
+    "@rudra-js/react": "^0.9.1",
     "react": "^18.2.0 || ^19.0.0"
   },
+  "peerDependenciesMeta": {
+    "@a2ui/react": {
+      "optional": true
+    },
+    "@rudra-js/react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@a2ui/react": "0.14.0",
     "@a2ui/web_core": "0.14.0",
-    "@rudra-js/core": "0.8.3",
-    "@rudra-js/react": "0.8.3",
+    "@rudra-js/core": "0.9.1",
+    "@rudra-js/react": "0.9.1",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "jsdom": "^27.4.0",

package/src/recommendation-messages.ts

@@ -0,0 +1,372 @@
+import type { A2uiMessage } from '@a2ui/web_core/v0_9';
+import type {
+  BannerBlock,
+  Block,
+  Bundle,
+  BundleBlock,
+  CopyBlock,
+  HeroBlock,
+  Product,
+  ProductReference,
+} from '@rudra-js/core';
+import type { RecommendationResult } from './recommendation-result.js';
+
+export interface RecommendationMessagesOptions {
+  surfaceId: string;
+  shopUrl: string;
+  catalogId?: string | undefined;
+  hrefForSku?: ((sku: string) => string) | undefined;
+  formatPrice?: ((product: Product) => string) | undefined;
+  formatBundlePrice?: ((bundle: Bundle) => string) | undefined;
+  locale?: string | undefined;
+}
+
+const BASIC_CATALOG_ID = 'https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json';
+const CARDS_PER_ROW = 2;
+
+type TextVariant = 'h2' | 'h3' | 'h4' | 'h5' | 'caption';
+
+interface OpenUrlAction {
+  functionCall: { call: 'openUrl'; args: { url: string }; returnType: 'void' };
+}
+
+type BasicComponent =
+  | { id: string; component: 'Text'; text: string; variant: TextVariant }
+  | { id: string; component: 'Image'; url: string; fit: 'cover'; variant: 'mediumFeature' }
+  | { id: string; component: 'Row'; children: string[]; align: 'start' }
+  | { id: string; component: 'Column'; children: string[]; align?: 'start'; weight?: number }
+  | { id: string; component: 'Card'; child: string; weight?: number }
+  | {
+      id: string;
+      component: 'Button';
+      child: string;
+      variant: 'borderless';
+      action: OpenUrlAction;
+    };
+
+interface BuildContext {
+  readonly products: ReadonlyMap<string, Product>;
+  readonly bundles: ReadonlyMap<string, Bundle>;
+  readonly shopUrl: string;
+  readonly linkFor: (sku: string) => string;
+  readonly formatPrice: (product: Product) => string;
+  readonly formatBundlePrice: (bundle: Bundle) => string;
+  readonly add: (component: BasicComponent) => string;
+}
+
+function defaultHrefForSku(sku: string): string {
+  return `/product/${encodeURIComponent(sku)}`;
+}
+
+function formatMoney(price: number, currency: string, locale: string | undefined): string {
+  let formatter: Intl.NumberFormat;
+  try {
+    formatter = new Intl.NumberFormat(locale, { style: 'currency', currency });
+  } catch {
+    return `${currency} ${price}`;
+  }
+  return formatter.format(price);
+}
+
+function defaultFormatPrice(product: Product, locale: string | undefined): string {
+  if (!Number.isFinite(product.price)) {
+    throw new TypeError(
+      `price for SKU ${product.sku} is ${String(product.price)}, not a finite number. ` +
+        'Catalog objects must satisfy productSchema from @rudra-js/core',
+    );
+  }
+  return formatMoney(product.price, product.currency, locale);
+}
+
+function defaultFormatBundlePrice(bundle: Bundle, locale: string | undefined): string {
+  if (!Number.isFinite(bundle.price)) {
+    throw new TypeError(
+      `price for bundle ${bundle.id} is ${String(bundle.price)}, not a finite number. ` +
+        'Bundle objects must satisfy bundleSchema from @rudra-js/core',
+    );
+  }
+  return formatMoney(bundle.price, bundle.currency, locale);
+}
+
+function toWebUrl(value: unknown, base: string | undefined, name: string): string {
+  if (typeof value !== 'string') throw new TypeError(`${name} is not a string`);
+  if (value.trim() === '') throw new TypeError(`${name} is empty`);
+  let url: URL;
+  try {
+    url = new URL(value, base);
+  } catch {
+    throw new TypeError(`${name} is not a URL: ${value}`);
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new TypeError(`${name} is not an http or https URL: ${value}`);
+  }
+  return url.href;
+}
+
+function plainText(value: string): string {
+  return value
+    .replace(/[\t\n\v\f\r \u0085\u2028\u2029]+/g, ' ')
+    .trim()
+    .replaceAll('[', '(')
+    .replaceAll(']', ')')
+    .replaceAll('<', '‹')
+    .replaceAll('>', '›');
+}
+
+function defined(ids: readonly (string | undefined)[]): string[] {
+  return ids.filter((id): id is string => id !== undefined);
+}
+
+function sellableProduct(context: BuildContext, sku: string): Product | undefined {
+  const product = context.products.get(sku);
+  return product?.isInStock === false ? undefined : product;
+}
+
+function addText(
+  context: BuildContext,
+  id: string,
+  value: string | null,
+  variant: TextVariant,
+): string | undefined {
+  const text = value === null ? '' : plainText(value);
+  return text ? context.add({ id, component: 'Text', text, variant }) : undefined;
+}
+
+function addStartColumn(
+  context: BuildContext,
+  id: string,
+  children: readonly (string | undefined)[],
+) {
+  return context.add({ id, component: 'Column', align: 'start', children: defined(children) });
+}
+
+function addColumn(context: BuildContext, id: string, children: readonly (string | undefined)[]) {
+  return context.add({ id, component: 'Column', children: defined(children) });
+}
+
+function addLink(context: BuildContext, id: string, sku: string, child: string): string {
+  const url = context.linkFor(sku);
+  return context.add({
+    id,
+    component: 'Button',
+    child,
+    variant: 'borderless',
+    action: { functionCall: { call: 'openUrl', args: { url }, returnType: 'void' } },
+  });
+}
+
+function addLinkedCard(
+  context: BuildContext,
+  id: string,
+  sku: string,
+  children: readonly (string | undefined)[],
+  weight: number | undefined,
+): string {
+  const link = addLink(context, `${id}_link`, sku, addStartColumn(context, `${id}_body`, children));
+  return context.add({
+    id,
+    component: 'Card',
+    child: link,
+    ...(weight === undefined ? {} : { weight }),
+  });
+}
+
+function addProductCard(
+  context: BuildContext,
+  id: string,
+  reference: ProductReference,
+  product: Product,
+): string {
+  const image = product.imageUrl?.trim()
+    ? context.add({
+        id: `${id}_image`,
+        component: 'Image',
+        url: toWebUrl(product.imageUrl, context.shopUrl, `the image for SKU ${product.sku}`),
+        fit: 'cover',
+        variant: 'mediumFeature',
+      })
+    : undefined;
+  return addLinkedCard(
+    context,
+    id,
+    product.sku,
+    [
+      image,
+      addText(context, `${id}_badge`, reference.badge, 'caption'),
+      addText(context, `${id}_title`, product.title, 'h5'),
+      addText(context, `${id}_price`, context.formatPrice(product), 'h5'),
+      addText(context, `${id}_reason`, reference.reason, 'caption'),
+    ],
+    1,
+  );
+}
+
+function addCardRows(
+  context: BuildContext,
+  id: string,
+  title: string | null,
+  items: readonly ProductReference[],
+): string | undefined {
+  const cards: string[] = [];
+  for (const reference of items) {
+    const product = sellableProduct(context, reference.sku);
+    if (product) {
+      cards.push(addProductCard(context, `${id}_item${cards.length}`, reference, product));
+    }
+  }
+  if (cards.length === 0) return undefined;
+
+  const rows: string[] = [];
+  for (let start = 0; start < cards.length; start += CARDS_PER_ROW) {
+    const rowId = `${id}_row${rows.length}`;
+    const row = cards.slice(start, start + CARDS_PER_ROW);
+    while (row.length < CARDS_PER_ROW) {
+      row.push(
+        context.add({
+          id: `${rowId}_space${row.length}`,
+          component: 'Column',
+          children: [],
+          weight: 1,
+        }),
+      );
+    }
+    rows.push(context.add({ id: rowId, component: 'Row', align: 'start', children: row }));
+  }
+  return addColumn(context, id, [addText(context, `${id}_title`, title, 'h3'), ...rows]);
+}
+
+function addHero(context: BuildContext, id: string, block: HeroBlock): string | undefined {
+  const product = block.sku === null ? undefined : sellableProduct(context, block.sku);
+  const headline = addText(context, `${id}_headline`, block.headline, 'h3');
+  const body = addText(context, `${id}_body`, block.body, 'caption');
+  if (!headline && !body && !product) return undefined;
+
+  const card = product
+    ? addLinkedCard(
+        context,
+        `${id}_product`,
+        product.sku,
+        [
+          addText(context, `${id}_product_title`, product.title, 'h4'),
+          addText(context, `${id}_product_price`, context.formatPrice(product), 'h5'),
+          addText(context, `${id}_product_cta`, block.ctaLabel, 'h5'),
+        ],
+        undefined,
+      )
+    : undefined;
+  return addStartColumn(context, id, [headline, body, card]);
+}
+
+function addBanner(context: BuildContext, id: string, block: BannerBlock): string {
+  const body = addStartColumn(context, `${id}_body`, [
+    addText(context, `${id}_text`, block.text, 'h5'),
+    addText(context, `${id}_cta`, block.ctaLabel, 'h5'),
+  ]);
+  return context.add({ id, component: 'Card', child: body });
+}
+
+function addCopy(context: BuildContext, id: string, block: CopyBlock): string {
+  return addStartColumn(context, id, [
+    addText(context, `${id}_title`, block.title, 'h3'),
+    addText(context, `${id}_body`, block.body, 'caption'),
+  ]);
+}
+
+function addBundle(context: BuildContext, id: string, block: BundleBlock): string | undefined {
+  const bundle = block.bundleId === null ? undefined : context.bundles.get(block.bundleId);
+  if (!bundle) return undefined;
+
+  const products: Product[] = [];
+  for (const sku of bundle.skus) {
+    const product = sellableProduct(context, sku);
+    if (!product) return undefined;
+    products.push(product);
+  }
+
+  const items = addStartColumn(
+    context,
+    `${id}_items`,
+    products.map((product, index) =>
+      addLink(
+        context,
+        `${id}_item${index}`,
+        product.sku,
+        context.add({
+          id: `${id}_item${index}_title`,
+          component: 'Text',
+          text: plainText(product.title) || plainText(product.sku),
+          variant: 'h5',
+        }),
+      ),
+    ),
+  );
+  const body = addStartColumn(context, `${id}_body`, [
+    addText(context, `${id}_label`, bundle.label ?? null, 'h3'),
+    addText(context, `${id}_title`, block.title, 'h4'),
+    addText(context, `${id}_text`, block.body, 'caption'),
+    items,
+    addText(context, `${id}_price`, context.formatBundlePrice(bundle), 'h5'),
+    addText(context, `${id}_cta`, block.ctaLabel, 'h5'),
+  ]);
+  return context.add({ id, component: 'Card', child: body });
+}
+
+function addBlock(context: BuildContext, id: string, block: Block): string | undefined {
+  switch (block.kind) {
+    case 'hero':
+      return addHero(context, id, block);
+    case 'grid':
+    case 'carousel':
+      return addCardRows(context, id, block.title, block.items);
+    case 'banner':
+      return addBanner(context, id, block);
+    case 'copy':
+      return addCopy(context, id, block);
+    case 'bundle':
+      return addBundle(context, id, block);
+    default:
+      block satisfies never;
+      return undefined;
+  }
+}
+
+export function buildRecommendationMessages(
+  result: RecommendationResult,
+  options: RecommendationMessagesOptions,
+): A2uiMessage[] {
+  const shopUrl = toWebUrl(options.shopUrl, undefined, 'the shop URL');
+  const hrefForSku = options.hrefForSku ?? defaultHrefForSku;
+  const components: BasicComponent[] = [];
+  const context: BuildContext = {
+    products: new Map(result.products.map((product) => [product.sku, product])),
+    bundles: new Map((result.bundles ?? []).map((bundle) => [bundle.id, bundle])),
+    shopUrl,
+    linkFor: (sku) => toWebUrl(hrefForSku(sku), shopUrl, `the link for SKU ${sku}`),
+    formatPrice: options.formatPrice ?? ((product) => defaultFormatPrice(product, options.locale)),
+    formatBundlePrice:
+      options.formatBundlePrice ?? ((bundle) => defaultFormatBundlePrice(bundle, options.locale)),
+    add: (component) => {
+      components.push(component);
+      return component.id;
+    },
+  };
+
+  const blocks = defined(
+    result.spec.blocks.map((block, index) => addBlock(context, `block${index}`, block)),
+  );
+  if (blocks.length === 0) return [];
+
+  addColumn(context, 'root', [
+    addText(context, 'headline', result.spec.headline, 'h2'),
+    addText(context, 'subheadline', result.spec.subheadline, 'caption'),
+    ...blocks,
+  ]);
+  const { surfaceId } = options;
+  return [
+    {
+      version: 'v0.9',
+      createSurface: { surfaceId, catalogId: options.catalogId ?? BASIC_CATALOG_ID },
+    },
+    { version: 'v0.9', updateComponents: { surfaceId, components } },
+  ];
+}

package/src/server.ts

@@ -9,4 +9,9 @@ export {
   type RecommendationRequest,
 } from './recommendation-request.js';
 
+export {
+  buildRecommendationMessages,
+  type RecommendationMessagesOptions,
+} from './recommendation-messages.js';
+
 export type { RecommendationResult } from './recommendation-result.js';