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; // before discounts
  finalPrice: number; // after discounts
  cumulativePercentageDiscount: number;
  appliedRewards: Array<{ id: string }>;
}

All ids are Shopify GIDs. Collection is { id, handle, title, products: Product[] } — products is populated for collectionMulti and empty for collectionSingle.

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 basePrice vs finalPrice per row, and totals.baseSubtotal vs totals.subtotal in the footer.
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. 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

Selector kinds

PDP add-to-cart override

When things go wrong

​The context object

​Hard rules

​The snapshot

​Selector kinds

​PDP add-to-cart override

​When things go wrong

The context object

Hard rules

The snapshot

Selector kinds

PDP add-to-cart override

When things go wrong