@rudra-js/a2ui 0.8.3 → 0.9.0

package/README.md

@@ -10,6 +10,8 @@ This package puts that block inside the interfaces an [A2UI](https://a2ui.org) a
 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`.
+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.
 
@@ -28,7 +30,11 @@ already has. Without `@latest`, an app on an older core can get an `ERESOLVE` er
 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.
+install `@rudra-js/core`, `@rudra-js/attested` and `@a2ui/web_core` for you, but not `@a2ui/react`,
+`@rudra-js/react` or `react`. Those three are optional, so a server that only builds
+[messages for other renderers](#flutter-angular-and-other-renderers) can leave React out. The
+browser component can't load without them, so keep them in the command. List the rest 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.
@@ -183,6 +189,75 @@ 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 only the basic catalog, which every renderer ships. A server with
+no React needs only 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.
+Those are for `RudraRecommendations`, which needs React. Use your own `surfaceId` in place of
+`'rudra_recommendations'`, and never name it 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. Or your agent's code can call it and pass the messages on to the client unchanged. Then
+the call has to carry the shopper's session, because `shopperFor` reads the shopper from the
+request. The first way is the safer one. Either way, keep the model away from the messages and
+from the block's surface, as
+[SECURITY.md](https://github.com/clivedsouza1010/rudra-js/blob/main/SECURITY.md) explains.
+
+- The messages create the surface named `surfaceId` and fill it. To show a new block there, send
+  `deleteSurface` for it first. When nothing in the block can be shown, you get no messages.
+- Grids and carousels show two cards to a row. The basic catalog can't fit cards to the screen, and
+  its `List` doesn't scroll on every renderer.
+- Each product card is a button that opens the product's page. `hrefForSku` builds the link,
+  `/product/<sku>` by default. `shopUrl` resolves that link and any relative image URL, because a
+  native app has no page to resolve them against. A product whose image URL is empty or only
+  spaces shows no image. A link that is empty, or a link or an image that doesn't end up `http` or
+  `https`, throws.
+- A featured card looks like any other, and a banner looks the same whatever its tone, because the
+  basic catalog has no styles for them. Nothing carries the `data-rudra-*` attributes the React
+  block uses for click tracking, so to count clicks, add a query parameter in `hrefForSku`.
+- Prices are formatted on your server, for `locale`. Without it, they use the server's default
+  locale, not the shopper's. Pass `formatPrice` and `formatBundlePrice` to format them yourself.
+- All text uses a heading or caption style, never body, because the web renderers read only body
+  text as Markdown. Flutter's `genui` and the A2UI SwiftUI renderer read every style 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, `<` and `>` become `‹` and `›`, and line breaks
+  become spaces. No text can load an image, and only a bare web address or email address can show
+  as a link. On SwiftUI a tap opens it. On `genui` it does nothing, and text that starts with `# `
+  or `- ` shows as Markdown.
+- The rationale and how the block was generated are never 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,
+  the app has to declare `https` links under `<queries>` in its manifest, or a tap on a card does
+  nothing.
+- On `@a2ui/angular` 0.13, register the `BasicCatalog` from `@a2ui/angular/v0_9`, because the one
+  from `@a2ui/angular` has the v1.0 id. Pass `useUniversalComponents: true` to `provideA2Ui` too,
+  next to `catalogs`. Without it, a click on a card does nothing, and each card tries to open its
+  link in a new tab as soon as it renders.
+
 ## zod
 
 A2UI's schemas use zod 3, so this package depends on zod 3. The rest of rudra-js uses zod 4. npm

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.0",
   "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.0",
+    "@rudra-js/react": "^0.9.0",
     "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.0",
+    "@rudra-js/react": "0.9.0",
     "@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';