@rudra-js/react 0.1.0

package/dist/rudra-component.d.ts

@@ -0,0 +1,60 @@
+import type { Bundle, ComponentSpec, Product } from '@rudra-js/core';
+import { type BlockRegistry } from './registry.js';
+export interface RudraComponentProps {
+    spec: ComponentSpec;
+    /**
+     * The host catalog. Every product fact on the page comes from here rather
+     * than from the specification.
+     *
+     * A list of products, or anything keyed by SKU — a `Map`, or your own view
+     * over a catalog too large to hold in one. The renderers only ever call
+     * `get(sku)` and `has(sku)`, so a view needs nothing else to be fast.
+     *
+     * Validate them with `productSchema` from `@rudra-js/core` — the same schema
+     * your candidates already passed — not with `parseTrackingInput`, which
+     * parses a whole tracking payload and will reject a bare catalog.
+     *
+     * This is a second door into the framework. `imageUrl` lands in an
+     * `<img src>`, and `productSchema` is the only thing that rejects a
+     * protocol-relative `//evil.example/pixel.png` or a `data:` URL — React
+     * neutralises `javascript:` on its own, but not those. A price that is not a
+     * finite number throws rather than rendering as free.
+     */
+    products: ProductCatalog;
+    /** Sets the shop sells together. Only needed if a spec can carry a bundle block. */
+    bundles?: readonly Bundle[];
+    registry?: BlockRegistry;
+    hrefForSku?: (sku: string) => string;
+    formatPrice?: (product: Product) => string;
+    /** Same as `formatPrice`, but for a bundle — the shop's price, not a sum of the parts. */
+    formatBundlePrice?: (bundle: Bundle) => string;
+    /**
+     * The shopper's locale, used to punctuate prices. Defaults to the server's,
+     * which is almost never the shopper's — pass it if the shop serves more than
+     * one. Ignored when `formatPrice` and `formatBundlePrice` are supplied.
+     */
+    locale?: string;
+    /**
+     * Adds the model's own reasoning, the provider and the model name to the
+     * markup. Useful while developing and while benchmarking; it publishes which
+     * vendor a shop uses and whether the component is currently degraded, so it
+     * is off unless asked for.
+     */
+    hasDiagnostics?: boolean;
+    className?: string;
+}
+/** A list of products, or anything keyed by SKU that answers `get` and `has`. */
+export type ProductCatalog = readonly Product[] | ReadonlyMap<string, Product>;
+/**
+ * Renders a component specification.
+ *
+ * A Server Component: no hooks, no state, no effects, and therefore no client
+ * bundle and no hydration for the recommendation area. The whole component
+ * arrives in the initial HTML response, which is what removes the pop-in a
+ * client-fetched recommendation rail has — and what makes the content visible
+ * to a crawler that does not run JavaScript.
+ *
+ * Renders nothing at all when no block produced markup.
+ */
+export declare function RudraComponent({ spec, products, bundles, registry, hrefForSku, formatPrice, formatBundlePrice, locale, hasDiagnostics, className, }: RudraComponentProps): import("react").JSX.Element | null;
+//# sourceMappingURL=rudra-component.d.ts.map

package/dist/rudra-component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rudra-component.d.ts","sourceRoot":"","sources":["../src/rudra-component.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAO5E,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAEpE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,aAAa,CAAC;IACpB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,EAAE,cAAc,CAAC;IACzB,oFAAoF;IACpF,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IACrC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC;IAC3C,0FAA0F;IAC1F,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,iFAAiF;AACjF,MAAM,MAAM,cAAc,GAAG,SAAS,OAAO,EAAE,GAAG,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAmG/E;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,EAC7B,IAAI,EACJ,QAAQ,EACR,OAAO,EACP,QAA0B,EAC1B,UAA8B,EAC9B,WAAW,EACX,iBAAiB,EACjB,MAAM,EACN,cAAsB,EACtB,SAAS,GACV,EAAE,mBAAmB,sCA0DrB"}

package/dist/rudra-component.js

@@ -0,0 +1,132 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { defaultFormatBundlePrice, defaultFormatPrice, defaultHrefForSku, } from './render-context.js';
+import { defaultRegistry } from './registry.js';
+/**
+ * Whether the catalog is already keyed by SKU.
+ *
+ * Asks what the renderers actually call rather than which class the host
+ * happened to construct. `instanceof Map` was wrong twice over: a Map that
+ * crossed a realm boundary — a `node:vm` context, a worker — fails it, and so
+ * does a host's own `ReadonlyMap`, which the prop type has always allowed. Both
+ * then fell into the list branch, where `catalog.map is not a function` throws
+ * while the render context is being built, before any block renders. That takes
+ * down the whole page, not just this component.
+ *
+ * Keyed before list, because a collection can answer both: an Immutable.js map
+ * has `map`, and converting through it yields a catalog whose every value is a
+ * `[sku, product]` pair rather than a product.
+ */
+function isKeyedBySku(catalog) {
+    const candidate = catalog;
+    return typeof candidate.get === 'function' && typeof candidate.has === 'function';
+}
+function toProductMap(catalog) {
+    if (isKeyedBySku(catalog))
+        return catalog;
+    if (typeof catalog.map !== 'function') {
+        // A Set of products, a plain object keyed by SKU, a Map that has been
+        // through JSON. Refusing here names the prop while the stack still points
+        // at it. Carried through instead, a grid renders nothing and a banner
+        // renders a healthy-looking page, and the shop finds out from a dashboard.
+        throw new TypeError('the `products` prop must be a list of products, or keyed by SKU with `get` and `has` — ' +
+            `received ${Object.prototype.toString.call(catalog)}`);
+    }
+    return new Map(catalog.map((product) => [product.sku, product]));
+}
+/**
+ * Whether a block still has anything to say once the catalog is applied.
+ *
+ * Three block kinds can come up empty: reconciliation ran against the catalog
+ * as it was when the spec was generated, and a SKU can sell out between then
+ * and this render. Grid and carousel lose just the products that did; a
+ * bundle loses itself entirely if any one of its members did. The rest carry
+ * their own words.
+ */
+function hasContent(block, products, bundles) {
+    switch (block.kind) {
+        case 'grid':
+        case 'carousel':
+            return block.items.some((reference) => products.has(reference.sku));
+        case 'hero':
+        case 'banner':
+        case 'copy':
+            return true;
+        case 'bundle': {
+            if (block.bundleId === null)
+                return false;
+            const bundle = bundles.get(block.bundleId);
+            return bundle !== undefined && bundle.skus.every((sku) => products.has(sku));
+        }
+        default:
+            // A kind this renderer predates renders nothing, so it counts as nothing.
+            block;
+            return false;
+    }
+}
+function renderBlock(block, context, registry, index) {
+    switch (block.kind) {
+        case 'hero':
+            return _jsx(registry.hero, { block: block, context: context }, index);
+        case 'grid':
+            return _jsx(registry.grid, { block: block, context: context }, index);
+        case 'carousel':
+            return _jsx(registry.carousel, { block: block, context: context }, index);
+        case 'banner':
+            return _jsx(registry.banner, { block: block, context: context }, index);
+        case 'copy':
+            return _jsx(registry.copy, { block: block, context: context }, index);
+        case 'bundle':
+            return _jsx(registry.bundle, { block: block, context: context }, index);
+        default:
+            // A newer core carrying a block kind this renderer predates loses that
+            // block rather than the page. In this repo the assertion below fails the
+            // build instead, which is the moment it is cheap to notice.
+            block;
+            return null;
+    }
+}
+/**
+ * Renders a component specification.
+ *
+ * A Server Component: no hooks, no state, no effects, and therefore no client
+ * bundle and no hydration for the recommendation area. The whole component
+ * arrives in the initial HTML response, which is what removes the pop-in a
+ * client-fetched recommendation rail has — and what makes the content visible
+ * to a crawler that does not run JavaScript.
+ *
+ * Renders nothing at all when no block produced markup.
+ */
+export function RudraComponent({ spec, products, bundles, registry = defaultRegistry, hrefForSku = defaultHrefForSku, formatPrice, formatBundlePrice, locale, hasDiagnostics = false, className, }) {
+    const productMap = toProductMap(products);
+    const bundlesById = new Map((bundles ?? []).map((bundle) => [bundle.id, bundle]));
+    const context = {
+        products: productMap,
+        bundles: bundlesById,
+        hrefForSku,
+        formatPrice: formatPrice ?? ((product) => defaultFormatPrice(product, locale)),
+        formatBundlePrice: formatBundlePrice ?? ((bundle) => defaultFormatBundlePrice(bundle, locale)),
+    };
+    // An empty recommendation area is worse than none: it takes up space and
+    // tells the shopper the page is broken. That includes the subtler version —
+    // a headline and an empty box, because every product in the spec has sold out
+    // since it was generated — which is why this asks what is left rather than
+    // how many blocks arrived.
+    const visible = spec.blocks.filter((block) => hasContent(block, context.products, context.bundles));
+    if (visible.length === 0)
+        return null;
+    // React omits a data-* attribute whose value is undefined, so degradedReason
+    // needs no branch of its own.
+    const diagnosticAttributes = hasDiagnostics
+        ? {
+            'data-rudra-provider': spec.provider ?? 'none',
+            'data-rudra-model': spec.model ?? 'none',
+            'data-rudra-latency-ms': String(spec.latencyMs),
+            'data-rudra-degraded': spec.degradedReason,
+        }
+        : undefined;
+    return (_jsxs("section", { 
+        // Extended rather than replaced: every child class is namespaced under
+        // `rudra`, and the package ships no stylesheet, so a host will pass one.
+        className: className ? `rudra ${className}` : 'rudra', "data-rudra-slot": spec.slot, "data-rudra-source": spec.source, "data-rudra-tone": spec.tone, ...diagnosticAttributes, children: [_jsxs("header", { className: "rudra__header", children: [_jsx("h2", { className: "rudra__headline", children: spec.headline }), spec.subheadline ? _jsx("p", { className: "rudra__subheadline", children: spec.subheadline }) : null] }), visible.map((block, index) => renderBlock(block, context, registry, index)), hasDiagnostics ? _jsx("p", { className: "rudra__rationale", children: spec.rationale }) : null] }));
+}
+//# sourceMappingURL=rudra-component.js.map

package/dist/rudra-component.js.map

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

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@rudra-js/react",
+  "version": "0.1.0",
+  "description": "Renders a rudra component specification as React Server Components",
+  "keywords": [
+    "react",
+    "react-server-components",
+    "rsc",
+    "llm",
+    "recommendations",
+    "ecommerce",
+    "ssr"
+  ],
+  "license": "MIT",
+  "author": "Clive Dsouza",
+  "homepage": "https://github.com/clivedsouza1010/rudra-js/tree/main/packages/react#readme",
+  "bugs": {
+    "url": "https://github.com/clivedsouza1010/rudra-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clivedsouza1010/rudra-js.git",
+    "directory": "packages/react"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@rudra-js/core": "^0.1.0",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@rudra-js/core": "0.1.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.5",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
+  }
+}

package/src/blocks/block-renderers.tsx

@@ -0,0 +1,102 @@
+/**
+ * Five of the six block renderers. The bundle one lives in `bundle-block.tsx`,
+ * next door, since it draws a set the shop picked rather than the model.
+ *
+ * Each takes a block the model produced and a context the host owns. None of
+ * them interpolate markup, and none of them read a product fact from the block
+ * — that is what keeps generated output to the role of deciding layout, order
+ * and wording.
+ */
+
+import type { BannerBlock, CarouselBlock, CopyBlock, GridBlock, HeroBlock } from '@rudra-js/core';
+import type { BlockRenderContext } from '../render-context.js';
+import { ProductCard } from './product-card.js';
+
+export function HeroRenderer({
+  block,
+  context,
+}: {
+  block: HeroBlock;
+  context: BlockRenderContext;
+}) {
+  const product = block.sku ? context.products.get(block.sku) : undefined;
+
+  return (
+    <section className="rudra-hero">
+      <h3 className="rudra-hero__headline">{block.headline}</h3>
+      {block.body ? <p className="rudra-hero__body">{block.body}</p> : null}
+      {product ? (
+        <a
+          className="rudra-hero__link"
+          href={context.hrefForSku(product.sku)}
+          data-rudra-sku={product.sku}
+        >
+          {product.title}
+          <span className="rudra-hero__price">{context.formatPrice(product)}</span>
+        </a>
+      ) : null}
+      {/* Only alongside a product: a "Shop now" with no destination is worse
+          than no call to action, and the model can set one for a SKU the
+          catalog does not have. */}
+      {product && block.ctaLabel ? <span className="rudra-hero__cta">{block.ctaLabel}</span> : null}
+    </section>
+  );
+}
+
+export function GridRenderer({
+  block,
+  context,
+}: {
+  block: GridBlock;
+  context: BlockRenderContext;
+}) {
+  return (
+    <section className="rudra-grid" data-rudra-columns={block.columns}>
+      {block.title ? <h3 className="rudra-grid__title">{block.title}</h3> : null}
+      <div className="rudra-grid__items">
+        {block.items.map((reference) => (
+          <ProductCard key={reference.sku} reference={reference} context={context} />
+        ))}
+      </div>
+    </section>
+  );
+}
+
+export function CarouselRenderer({
+  block,
+  context,
+}: {
+  block: CarouselBlock;
+  context: BlockRenderContext;
+}) {
+  return (
+    <section className="rudra-carousel">
+      {block.title ? <h3 className="rudra-carousel__title">{block.title}</h3> : null}
+      {/* Scrolls with CSS overflow rather than JavaScript, so the whole
+          component still needs no client bundle. */}
+      <div className="rudra-carousel__track">
+        {block.items.map((reference) => (
+          <ProductCard key={reference.sku} reference={reference} context={context} />
+        ))}
+      </div>
+    </section>
+  );
+}
+
+export function BannerRenderer({ block }: { block: BannerBlock }) {
+  return (
+    <aside className="rudra-banner" data-rudra-banner-tone={block.tone}>
+      <span className="rudra-banner__text">{block.text}</span>
+      {block.ctaLabel ? <span className="rudra-banner__cta">{block.ctaLabel}</span> : null}
+    </aside>
+  );
+}
+
+export function CopyRenderer({ block }: { block: CopyBlock }) {
+  return (
+    <section className="rudra-copy">
+      {block.title ? <h3 className="rudra-copy__title">{block.title}</h3> : null}
+      <p className="rudra-copy__body">{block.body}</p>
+    </section>
+  );
+}

package/src/blocks/bundle-block.tsx

@@ -0,0 +1,43 @@
+import type { BundleBlock, Product } from '@rudra-js/core';
+import type { BlockRenderContext } from '../render-context.js';
+
+export function BundleRenderer({
+  block,
+  context,
+}: {
+  block: BundleBlock;
+  context: BlockRenderContext;
+}) {
+  const bundle = block.bundleId === null ? undefined : context.bundles.get(block.bundleId);
+  if (!bundle) return null;
+
+  const products: Product[] = [];
+  for (const sku of bundle.skus) {
+    const product = context.products.get(sku);
+    // A set missing one of its parts is not that set.
+    if (!product) return null;
+    products.push(product);
+  }
+
+  return (
+    <section className="rudra-bundle">
+      {/* The shop's label is the one name here anyone can check, so it leads. */}
+      {bundle.label ? <h3 className="rudra-bundle__label">{bundle.label}</h3> : null}
+      {block.title ? <p className="rudra-bundle__title">{block.title}</p> : null}
+      {block.body ? <p className="rudra-bundle__body">{block.body}</p> : null}
+
+      <ul className="rudra-bundle__items">
+        {products.map((product) => (
+          <li key={product.sku} className="rudra-bundle__item" data-rudra-sku={product.sku}>
+            <a className="rudra-bundle__link" href={context.hrefForSku(product.sku)}>
+              {product.title}
+            </a>
+          </li>
+        ))}
+      </ul>
+
+      <p className="rudra-bundle__price">{context.formatBundlePrice(bundle)}</p>
+      {block.ctaLabel ? <span className="rudra-bundle__cta">{block.ctaLabel}</span> : null}
+    </section>
+  );
+}

package/src/blocks/product-card.tsx

@@ -0,0 +1,45 @@
+import type { ProductReference } from '@rudra-js/core';
+import type { BlockRenderContext } from '../render-context.js';
+
+/**
+ * One product.
+ *
+ * Every fact here — the title, the price, the image, the link — is read from
+ * the catalog, not from the specification. The only things the model
+ * contributes are `reason`, `badge` and `emphasis`, and React escapes all three
+ * on the way into the markup.
+ */
+export function ProductCard({
+  reference,
+  context,
+}: {
+  reference: ProductReference;
+  context: BlockRenderContext;
+}) {
+  const product = context.products.get(reference.sku);
+  // Reconciliation drops a SKU the catalog does not have, so this should be
+  // unreachable. Rendering nothing beats rendering a card with holes in it.
+  if (!product) return null;
+
+  const isFeatured = reference.emphasis === 'featured';
+
+  return (
+    <a
+      href={context.hrefForSku(product.sku)}
+      data-rudra-sku={product.sku}
+      data-rudra-basis={reference.basis}
+      className={isFeatured ? 'rudra-card rudra-card--featured' : 'rudra-card'}
+    >
+      {product.imageUrl ? (
+        <img className="rudra-card__image" src={product.imageUrl} alt="" loading="lazy" />
+      ) : null}
+
+      <span className="rudra-card__body">
+        {reference.badge ? <span className="rudra-card__badge">{reference.badge}</span> : null}
+        <span className="rudra-card__title">{product.title}</span>
+        <span className="rudra-card__price">{context.formatPrice(product)}</span>
+        {reference.reason ? <span className="rudra-card__reason">{reference.reason}</span> : null}
+      </span>
+    </a>
+  );
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @rudra-js/react — renders a component specification as React Server Components.
+ *
+ * Carries no client JavaScript. The recommendation area arrives in the initial
+ * HTML response and needs no hydration.
+ */
+
+export {
+  RudraComponent,
+  type ProductCatalog,
+  type RudraComponentProps,
+} from './rudra-component.js';
+
+export {
+  defaultRegistry,
+  extendRegistry,
+  type BlockRegistry,
+  type BlockRenderer,
+} from './registry.js';
+
+export {
+  defaultFormatBundlePrice,
+  defaultFormatPrice,
+  defaultHrefForSku,
+  type BlockRenderContext,
+} from './render-context.js';
+
+// The six default renderers reach hosts through `defaultRegistry`, which is
+// also the thing they need in order to override one. `ProductCard` is exported
+// on its own because a custom grid renderer still wants the standard card.
+export { ProductCard } from './blocks/product-card.js';

package/src/registry.ts

@@ -0,0 +1,59 @@
+/**
+ * What each kind of block actually renders.
+ *
+ * This is the seam that makes a generated component safe *and* usable. The
+ * model picks from a fixed vocabulary of block kinds; the registry decides what
+ * those kinds look like. A shop can swap any entry for its own design-system
+ * component without the model knowing, without the specification changing, and
+ * without giving the model any new ability — it still cannot say anything
+ * outside the vocabulary.
+ */
+
+import type { ReactNode } from 'react';
+import type { Block, BlockKind } from '@rudra-js/core';
+import type { BlockRenderContext } from './render-context.js';
+import {
+  BannerRenderer,
+  CarouselRenderer,
+  CopyRenderer,
+  GridRenderer,
+  HeroRenderer,
+} from './blocks/block-renderers.js';
+import { BundleRenderer } from './blocks/bundle-block.js';
+
+export type BlockRenderer<Kind extends BlockKind> = (props: {
+  block: Extract<Block, { kind: Kind }>;
+  context: BlockRenderContext;
+}) => ReactNode;
+
+export type BlockRegistry = {
+  [Kind in BlockKind]: BlockRenderer<Kind>;
+};
+
+export const defaultRegistry: BlockRegistry = {
+  hero: HeroRenderer,
+  grid: GridRenderer,
+  carousel: CarouselRenderer,
+  banner: BannerRenderer,
+  copy: CopyRenderer,
+  bundle: BundleRenderer,
+};
+
+/**
+ * Replaces some renderers and keeps the rest.
+ *
+ * Written out kind by kind rather than spread: a spread lets
+ * `{ hero: maybeRenderer }` put an explicit `undefined` over the default, and
+ * the page then renders every hero as nothing. Here an absent override means
+ * the default, however it was written.
+ */
+export function extendRegistry(overrides: Partial<BlockRegistry>): BlockRegistry {
+  return {
+    hero: overrides.hero ?? defaultRegistry.hero,
+    grid: overrides.grid ?? defaultRegistry.grid,
+    carousel: overrides.carousel ?? defaultRegistry.carousel,
+    banner: overrides.banner ?? defaultRegistry.banner,
+    copy: overrides.copy ?? defaultRegistry.copy,
+    bundle: overrides.bundle ?? defaultRegistry.bundle,
+  };
+}

package/src/render-context.ts

@@ -0,0 +1,99 @@
+import type { Bundle, Product } from '@rudra-js/core';
+
+/**
+ * Everything a block renderer needs that does not come from the specification.
+ *
+ * Note what is absent from the spec and present here: a price, a title, an
+ * image, a link. Those are resolved from the host's own catalog, keyed by a SKU
+ * that `selectProducts` drew from that same catalog and `reconcileSpec` proved
+ * the model did not invent — both in stock at the time. A bundle member's SKU
+ * comes from the set the shop supplied, not from the model. That division
+ * is the whole reason a generated component is safe to put in a page — the
+ * model decides what to show and how to describe it, and the shop decides what
+ * is true about a product.
+ */
+export interface BlockRenderContext {
+  /** The host's catalog, keyed by SKU. Read-only: it is the caller's own map. */
+  readonly products: ReadonlyMap<string, Product>;
+  /** Sets the shop sells together, keyed by id. */
+  readonly bundles: ReadonlyMap<string, Bundle>;
+  /** Host-owned link construction. */
+  readonly hrefForSku: (sku: string) => string;
+  readonly formatPrice: (product: Product) => string;
+  readonly formatBundlePrice: (bundle: Bundle) => string;
+}
+
+export function defaultHrefForSku(sku: string): string {
+  return `/product/${encodeURIComponent(sku)}`;
+}
+
+/**
+ * Formats a price the way the currency itself is written.
+ *
+ * No digit count is specified on purpose. Two decimal places is a dollar-and-
+ * cent assumption, and forcing it is wrong in both directions: Kuwaiti dinar and
+ * Bahraini dinar have three, so a real digit of the price disappears, and yen has
+ * none, so a price gains a fraction that does not exist. Intl already knows the
+ * right number for each currency.
+ *
+ * `locale` decides how the number is punctuated and where the symbol sits.
+ * Left undefined it falls back to the server's locale, which is almost never
+ * the shopper's — a shop serving more than one should pass the shopper's.
+ */
+export function defaultFormatPrice(product: Product, locale?: string): string {
+  // A price that is not a finite number is a broken catalog, not a formatting
+  // problem, and Intl will happily render it: null becomes 0 and prints as a
+  // free product, undefined prints as NaN. Neither belongs on a shop page, and
+  // both mean the catalog skipped the validation this package documents as a
+  // precondition. Failing here is a bug report; rendering it is an incident.
+  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',
+    );
+  }
+
+  let formatter: Intl.NumberFormat;
+  try {
+    // Only the constructor is guarded. Wrapping format() as well would swallow
+    // a throwing getter on a host's own Product object and render the resulting
+    // mess as a price.
+    formatter = new Intl.NumberFormat(locale, { style: 'currency', currency: product.currency });
+  } catch {
+    // Two things reach this. A malformed `locale`, which is a host prop nothing
+    // validates. And a malformed `currency` — which productSchema would have
+    // rejected, but this package takes a catalog directly, so a hand-built
+    // object can carry one. Intl accepts any three-letter code it does not
+    // know, so 'ZZZ' formats; 'us$' and '' do not. A price nobody can
+    // punctuate is still a price worth showing.
+    return `${product.currency} ${product.price}`;
+  }
+
+  return formatter.format(product.price);
+}
+
+/**
+ * Formats a bundle's price, in the currency the shop put on the bundle.
+ *
+ * The price and the currency come from the same object, so a set whose members
+ * are priced in another currency still shows the shop's own price correctly.
+ */
+export function defaultFormatBundlePrice(bundle: Bundle, locale?: string): 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',
+    );
+  }
+
+  try {
+    return new Intl.NumberFormat(locale, {
+      style: 'currency',
+      currency: bundle.currency,
+    }).format(bundle.price);
+  } catch {
+    // A bad locale, or a currency code Intl rejects on a hand-built bundle,
+    // should not crash the page. A price nobody can punctuate is still a price.
+    return `${bundle.currency} ${bundle.price}`;
+  }
+}