Renderer function

The JS asset must call defineRenderer exactly once, at the top level:

window.nameless.defineRenderer(function (ctx) {
  ctx.container.innerHTML = "<div class='nb-bundle'>…</div>";
});

Do not wrap the call in DOMContentLoaded, setTimeout, or a conditional guard. Registration is matched to the loading bundle via document.currentScript, so a deferred call registers against nothing and the widget never renders.

The context object

Field	Type	Notes
`snapshot`	`BundleSnapshot`	Read-only current state of this bundle
`container`	`HTMLElement`	Paint here. Already carries `data-nameless-widget="{bundleId}"`
`locale`	`string`	Canonical BCP-47 tag (`"en"`, `"pt-BR"`). Safe for `Intl.*`. Never null
`t`	`(source, vars?) => string`	Translates merchant-visible copy

There is no dispatch in the context — don’t look for one. ctx.t uses the English source string as the key, so there are no key names to invent:

ctx.t("Add to cart");
ctx.t("Save {{percent}}%", { percent: 15 });

A missing translation renders the literal you wrote, never a blank or a key. If you are editing a renderer that already ships ctx.t("…") literals, keep them byte-for-byte — the literal is the key to the merchant’s stored translations, and rewording it orphans every locale. Change the markup around a literal rather than the literal itself. Translate whole phrases, never fragments you concatenate, and avoid fixed-width buttons: translated copy runs up to 50% longer.

Hard rules

Rule	Why
No `addEventListener`, no inline `on*=""`	The runtime owns interactivity; your handlers die on the next repaint
No `window.nameless.dispatch(...)`	State changes come from the attribute contract, not the renderer
No `fetch` / `XMLHttpRequest`	Everything you may render is already in the snapshot
No globals, no `localStorage`, no timers	The renderer must be a pure function of the snapshot
Never cache DOM nodes between calls	Each call replaces the markup
Escape every snapshot string	Product titles are merchant input

Escaping helper — apply to anything out of snapshot, never to ctx.t output (it escapes itself, and double-escaping shows shoppers "):

function esc(s) {
  return String(s)
    .replace(/&/g, "&amp;")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;");
}

The snapshot

interface BundleSnapshot {
  bundleId: string;
  meta: { title: string; subtitle: string | null; atcOverride: boolean };
  selectors: NormalizedSelector[];
  selections: { [selectorId: string]: null | SelectionEntry | SelectionEntry[] };
  conditionSets: ConditionSet[]; // discount rules; rarely rendered directly
  status: "idle" | "ready" | "invalid";
  totals: {
    itemCount: number;
    baseSubtotal: number; // before discounts
    subtotal: number; // after discounts
    currencyCode: string | null;
  };
}

type NormalizedSelector =
  | { kind: "productSingle"; id: string; product: Product }
  | {
      kind: "collectionSingle";
      id: string;
      collection: Collection;
      resolvedProduct: Product | null;
    }
  | { kind: "collectionMulti"; id: string; collection: Collection };

interface Product {
  id: string;
  handle: string;
  title: string;
  variants: Array<{
    id: string; // → <option value>
    title: string;
    priceAmount: number;
    currencyCode: string;
    available: boolean;
    image: {
      url: string;
      altText: string | null;
      width: number | null;
      height: number | null;
    } | null;
    inventoryQuantity: number | null;
  }>;
}

interface SelectionEntry {
  productId: string;
  variantId: string;
  quantity: number;
  soldOut: boolean;
  basePrice: number; // this entry's own price, per unit, before discounts
  finalPrice: number; // per unit, after discounts (≤ basePrice)
  cumulativePercentageDiscount: number; // not a sum — see the pricing rules below
  appliedRewards: Array<{ id: string }>; // at most one: the reward that reduced this entry
}

The snapshot also carries version: number (the bundle’s revision, used internally for cart stamping) — renderers have no reason to read it. All ids are Shopify GIDs. Collection is { id, handle, title, products: Product[] } — products is populated for collectionMulti and empty for collectionSingle.

Pricing rules

Prices are per unit on every entry, for every selector kind, and each entry carries its own — a collectionMulti row shows that product’s price, not the selector’s total. Multiply by entry.quantity yourself if you want a line total. Four rules beyond that:

Rule	What to do
`cumulativePercentageDiscount` is not a sum. At most one reward reduces an entry; the name is historical. It is `0` when that reward was a fixed amount and when nothing applied — `0` does not mean “no discount”	Show a percentage only when it’s non-zero. To detect a discount at all, compare `basePrice` against `finalPrice`
The footer is the authoritative total. `totals` sums at the line level, where the discount logic rounds; adding up per-unit prices × quantity yourself can drift a cent or two when a fixed amount splits unevenly	Take the footer figures from `totals`, not from your own sum of the rows
Money rewards are converted for display. In a currency other than the shop’s, the widget converts fixed amounts with the page’s exchange rate; checkout re-reads that rate, so the two can differ by up to a cent per line	Present the widget total as the widget’s figure; don’t promise it matches checkout to the cent
Two-decimal currencies are assumed. Rounding runs in integer cents, so zero-decimal (JPY, KRW) and three-decimal (KWD, BHD) currencies can be off by a fraction of a unit — a known open bug	Format with `Intl.NumberFormat(ctx.locale, { style: "currency", currency })` rather than hand-rolled decimals

An entry with nothing applied — including a row the shopper hasn’t picked — reports its variant’s unit price with an empty appliedRewards. Above all: never recompute a discount yourself from conditionSets. Discount math is shared with the checkout-side function; re-deriving it in a renderer will disagree with what the shopper is charged.

Selector kinds

`kind`	Render	Products from	`selections[sel.id]`
`productSingle`	One product row	`sel.product`	entry or `null`
`collectionSingle`	One row when `resolvedProduct` is set, else an empty state	`sel.resolvedProduct`	entry or `null`
`collectionMulti`	One row per collection product	`sel.collection.products`	array of entries (may be `[]`)

Reading recipes:

Iterate snapshot.selectors and branch on sel.kind before touching product data.
Single selectors: guard with Array.isArray(entry) and treat an array as null. Use entry.variantId for the selected <option>, entry.quantity for the qty control.
collectionMulti: for each product in sel.collection.products, find its state by matching entry.productId === product.id inside the array. Quantity 0 means unselected; on first load the array is empty, so every row shows 0.
Never hardcode a starting quantity. The engine sets initial quantities from the bundle’s first condition set before the first render — display entry.quantity.
Never fetch collection members yourself; they arrive in the snapshot.
Show discounts by comparing totals.baseSubtotal vs totals.subtotal in the footer, and basePrice vs finalPrice per row — see the pricing rules above.
Derive currency from the variant’s currencyCode or totals.currencyCode.
Handle collectionSingle with resolvedProduct: null — don’t invent a product.

PDP add-to-cart override

snapshot.meta.atcOverride is a merchant setting, not something the renderer controls. When it is true, the theme’s own add-to-cart button drives the bundle: the widget is mounted directly above it and the host intercepts the native click. Branch your footer on it: when atcOverride is true, omit your own ATC button entirely (the host strips stray [data-nameless-atc] nodes as a safety net). When it is false, render the button as usual. Trust the flag and nothing else. A bundle the merchant configured as a popup always arrives with atcOverride: false, because in that mode the theme button opens the popup and your button is the only way to add — the host rewrites the flag before your renderer sees it, so there is no popup case to special-case. See Shopify integration and Resolver stages.

When things go wrong

The host logs structured codes prefixed with [nameless]:

Code	Meaning	Effect
`RENDERER_THREW`	Your callback threw	Container keeps the last successful paint (or stays empty)
`RENDERER_LOAD_ERROR`	The CSS fetch or the JS `<script>` failed	Widget does not render at all for that bundle
`RENDERER_MOUNT_NOT_FOUND`	No `[data-nameless-block]` element on the page	Renderer never called — the theme block is missing

Stay defensive: guard against empty selectors, null selections, empty collection.products, and missing image. If CSS fails, the JS is not executed, so treat both assets as required — but still write semantic, labelled markup so the widget survives a styling regression. Next: the data attributes the runtime wires after each paint.

Get Started

Guides

Integrations

Help

Renderer function

The context object

Hard rules

The snapshot

Pricing rules

Selector kinds

PDP add-to-cart override

When things go wrong

​The context object

​Hard rules

​The snapshot

​Pricing rules

​Selector kinds

​PDP add-to-cart override

​When things go wrong

The context object

Hard rules

The snapshot

Pricing rules

Selector kinds

PDP add-to-cart override

When things go wrong