Sources

A source is a lookup from a request URL to your source-of-truth data. Return the data when the URL is yours; return null (or undefined) when it isn’t. Sync or async both work, but resolvers run on the edge hot path (p95 < 50ms compute budget), so back them with your in-memory catalog, a KV cache, or a fast local store, not an origin round-trip.

interface GatewaySources {            // all optional; missing source => pass through
  // Commerce shaped.
  product?:    SourceResolver<ProductSource>        // a product detail page
  policies?:   SourceResolver<PolicySource[]>       // shipping, returns, warranty
  catalog?:    SourceResolver<CatalogItemSource[]>  // a priced listing

  // Universal: any page on any site, and any index of them.
  document?:   SourceResolver<DocumentSource>       // a guide, article, service, location, FAQ
  collection?: SourceResolver<CollectionSource>     // an index of documents

  // Optional router. Pure and synchronous. When it names a kind, that resolver
  // is the only one called. Return null to use the fixed order below.
  match?: (url: URL) => SourceKind | null
}

type SourceResolver<T> = (url: URL) => T | null | undefined | Promise<T | null | undefined>
type SourceKind = 'product' | 'policies' | 'catalog' | 'document' | 'collection'

• The order is fixed: product → policies → catalog → document → collection. The first source returning data wins, so product wins when several would match a URL. The two universal sources sit below the three commerce ones, which is what makes them safe to add: a store that wires site-wide documents keeps its PDPs rendering as PDPs. Narrow the higher-precedence resolver when two would match. There is no separate setting for it.
• A source that throws is treated as "no match" and resolution continues with the next source. It never breaks your site.
• If the render itself fails, the request passes through to HTML; the gateway never substitutes a lower-precedence document for the one that matched.
• An empty policies/catalog array is no match. So is a missing source: configure only the resolvers you have.

One product detail page. Rendering order is fixed and front-loaded: title (linked to the canonical URL) → brand → price (compare-at struck through when present: ~~$120.00~~ $89.00) → availability → shipping → returns → variants table → description → attributes → images as markdown links. Absent optionals render nothing.

Policy documents (shipping, returns, warranty, …), rendered as linked headings + verbatim bodies.

Collection/catalog listings, rendered as a markdown table (linked title, price, availability).

Any page that is not a product, a policy set, or a priced listing. A guide, a service, a location, an article, an FAQ, a plan, a profile, a job posting. Most of a site is usually documents, and a site with no catalog wires this and collection and nothing else.

The shape is the same promise as the commerce types: every field is authoritative data you supply, and the renderer only transforms format. It never invents, estimates, or rewords a value.

A Fact is { label, value, note? }, and value is a closed union so every rendering is deterministic and locale-free: text, list, number (with an optional unit), boolean (rendered as a fixed Yes/No), money (with an optional maxValue for a range, and period or per), date (ISO 8601, verbatim), url (scheme allowlisted), and hours.

hours renders a markdown table from { weekly, exceptions?, timeZone, note? }. timeZone is required, because hours without a zone are an ambiguous fact. A weekday with intervals: [] is Closed; a weekday absent from weekly renders Not stated, which is a different fact. The renderer never computes "open now": that is the agent’s job, and doing it here would be inventing a value.

An index of documents. A guides hub, a services list, a locations directory, a blog archive. Where catalog is the priced listing, this is the unpriced one: it renders as a link list, or as a table when the items carry facts.

Items carrying no facts render as a link list. Give the items facts and the same listing renders as a table, which is what makes a 3,000-page guide index answerable in one fetch instead of three thousand.

A non-integer amount throws rather than rounds, because silently altering a price is never acceptable.

Size budget: output is capped at maxBytes (default 5120 bytes, UTF-8). Buying facts are front-loaded, and truncation only ever removes content from the bottom (description, attributes, images) on whole lines, appending a fixed truncation note; the front-loaded facts and the variants table are never removed. If the facts alone exceed the budget, they are emitted anyway: facts are never sacrificed to the byte budget.