create-skybridge 0.0.0-dev.7914624 → 0.0.0-dev.793efe5

package/templates/ecom/src/lib/variants.ts

@@ -1,79 +1,150 @@
-import type { Product, Variant } from "../tools/render-carousel.js";
+import type { Product, Variant } from "../types.js";
 
 // Pure helpers that turn the client's option choices into a concrete variant.
 // The `variants` list is SPARSE: only combinations that exist are present, and
 // that is the whole contingency model. These helpers never encode rules; they
-// filter the list.
+// filter the list. A variant may also skip an axis entirely (a one-size cap in
+// a capacity x size catalog carries no `size`): that axis is simply "not
+// applicable" to it, and the helpers treat the absence as its own value.
+//
+// Availability is computed TOP-DOWN (the Shopify convention): an axis is
+// constrained only by the choices on the axes declared BEFORE it. So the first
+// axis is never disabled by a later choice, and each later axis narrows under
+// the ones above. Order the `options` array accordingly.
 
 // A selection is one chosen value per axis, keyed by Option.id -> OptionValue.id.
 export type Selection = Record<string, string>;
 
 /**
- * The variant matching a full selection (one value per axis), or undefined if
- * the selection is partial or the combination does not exist. A product with no
- * options resolves to its single variant on an empty selection.
+ * The variant that exactly matches a selection, or undefined if none does.
+ * Strict per-axis equality with "missing" normalized to null: a partial
+ * selection resolves nothing, and a variant that skips an axis matches only a
+ * selection that also leaves it unset. A product with no options resolves to
+ * its single variant on an empty selection.
  */
 export function resolveVariant(
   product: Product,
   selection: Selection,
 ): Variant | undefined {
-  for (const option of product.options) {
-    if (selection[option.id] == null) {
-      return undefined; // partial selection: nothing resolved yet
-    }
-  }
   return product.variants.find((variant) =>
     product.options.every(
-      (option) => variant.selection[option.id] === selection[option.id],
+      (option) =>
+        (variant.selection[option.id] ?? null) ===
+        (selection[option.id] ?? null),
     ),
   );
 }
 
 /**
- * The values of `axisId` still reachable given the choices already made on the
- * OTHER axes. A value is reachable if at least one variant carries it while
- * matching every other current choice. Values not in this set have no surviving
- * variant, so the picker disables them ("Red only in M").
+ * The state of every value of `axisId` given the choices on the axes ABOVE it:
+ * - "inStock": at least one matching variant is purchasable → normal chip.
+ * - "soldOut": matching variants exist, none in stock → struck, clickable.
+ * - absent: a hole in the variant matrix → hard-disabled chip.
+ * An empty map means the axis does not apply to the current configuration (a
+ * one-size colorway has no Size), and the picker hides its row.
  */
-export function selectableValues(
+export function axisStates(
   product: Product,
   axisId: string,
   selection: Selection,
-): Set<string> {
-  const reachable = new Set<string>();
+): Map<string, "inStock" | "soldOut"> {
+  const states = new Map<string, "inStock" | "soldOut">();
   for (const variant of product.variants) {
-    let matchesOthers = true;
+    let matchesEarlier = true;
     for (const option of product.options) {
       if (option.id === axisId) {
-        continue;
+        break; // only the axes above constrain this one
       }
       const chosen = selection[option.id];
-      if (chosen != null && variant.selection[option.id] !== chosen) {
-        matchesOthers = false;
+      const carried = variant.selection[option.id];
+      if (chosen != null && carried !== undefined && carried !== chosen) {
+        matchesEarlier = false;
+        break;
+      }
+    }
+    if (!matchesEarlier) {
+      continue;
+    }
+    // A variant to which this axis does not apply carries no value to offer.
+    const value = variant.selection[axisId];
+    if (value !== undefined && states.get(value) !== "inStock") {
+      states.set(value, variant.outOfStock ? "soldOut" : "inStock");
+    }
+  }
+  return states;
+}
+
+/**
+ * The selection after picking `valueId` on `axisId`: the one state transition
+ * of the picker, rebuilt top-down.
+ * - An axis with no reachable value does not apply: its choice is dropped.
+ * - A prior choice that still EXISTS under the axes above is KEPT, even sold
+ *   out: switching color never silently changes the size the user asked for.
+ * - Anything else fills with the first value in display order, preferring one
+ *   that is in stock.
+ * The result resolves to a concrete variant, with one exception: a variant
+ * skipping an EARLIER axis keeps offering its later values under any choice on
+ * that axis, so picking one can compose a selection no variant matches. The
+ * detail renders that as "Combination unavailable".
+ */
+export function applyChoice(
+  product: Product,
+  selection: Selection,
+  axisId: string,
+  valueId: string,
+): Selection {
+  const next: Selection = {};
+  for (const option of product.options) {
+    const candidate = option.id === axisId ? valueId : selection[option.id];
+    const states = axisStates(product, option.id, next);
+    if (states.size === 0) {
+      continue; // axis does not apply to the configuration above it
+    }
+    if (candidate != null && states.has(candidate)) {
+      next[option.id] = candidate;
+      continue;
+    }
+    let fill: string | undefined;
+    for (const value of option.values) {
+      if (states.get(value.id) === "inStock") {
+        fill = value.id;
         break;
       }
     }
-    if (matchesOthers) {
-      reachable.add(variant.selection[axisId]);
+    if (fill === undefined) {
+      for (const value of option.values) {
+        if (states.has(value.id)) {
+          fill = value.id;
+          break;
+        }
+      }
+    }
+    if (fill !== undefined) {
+      next[option.id] = fill;
     }
   }
-  return reachable;
+  return next;
 }
 
 /**
  * The selection to preselect when a product opens: the variant the client
- * tapped (its id equals the opened product id), else the first variant. A
- * variant is always preselected when the product has any, so the buy CTA is
- * live on open rather than starting disabled.
+ * tapped (its id equals the opened product id), else the first IN-STOCK
+ * variant, else the first variant. A variant is always preselected when the
+ * product has any, so the buy CTA is live on open rather than starting
+ * disabled.
  */
 export function initialSelection(product: Product): Selection {
   let base: Variant | undefined;
+  let firstInStock: Variant | undefined;
   for (const variant of product.variants) {
     if (variant.id === product.id) {
       base = variant;
       break;
     }
+    if (firstInStock === undefined && !variant.outOfStock) {
+      firstInStock = variant;
+    }
   }
-  base ??= product.variants[0];
+  base ??= firstInStock ?? product.variants[0];
   return base ? { ...base.selection } : {};
 }

package/templates/ecom/src/server.ts

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { McpServer } from "skybridge/server";
+import { Skybridge } from "skybridge/server";
 import { CAROUSEL_RANGE, MIN_SEARCH_ITERATIONS } from "./config.js";
 import {
   renderCarouselDefinition,
@@ -15,29 +15,25 @@ if (existsSync(".env")) {
   process.loadEnvFile();
 }
 
-const server = new McpServer(
-  {
-    // @todo: name and version your app.
-    name: "skybridge-ecom",
-    version: "0.0.1",
-  },
-  {
-    // @todo: adapt this server-wide prompt to your catalog.
-    instructions: `\
+export const app = new Skybridge({
+  // @todo: name and version your app.
+  name: "skybridge-ecom",
+  version: "0.0.1",
+  // @todo: adapt this server-wide prompt to your catalog.
+  instructions: `\
 Two phases:
 
-SEARCH: Call search-products ${MIN_SEARCH_ITERATIONS}+ times before presenting—never off one call. \
-Vary the keyword, apply filters from a prior response, or page deeper. \
+SEARCH: Call search-products ${MIN_SEARCH_ITERATIONS}+ times before presenting, never off one call. \
+Vary the keywords or page deeper. \
 Stay silent while searching: emit NO text between calls. Speak only \
-once the carousel renders. Never call a category unavailable before searching.
+once the carousel renders.
 
 RENDER: After curating, call render-carousel with the chosen product IDs (aim for ${CAROUSEL_RANGE}). \
-Speak only once it renders, then recommend in carousel order.`,
-  },
-)
-  .registerTool(searchProductsDefinition, searchProductsHandler)
-  .registerTool(renderCarouselDefinition, renderCarouselHandler);
+Speak once it renders, then recommend products in carousel order.`,
+  handler: (server) =>
+    server
+      .registerTool(searchProductsDefinition, searchProductsHandler)
+      .registerTool(renderCarouselDefinition, renderCarouselHandler),
+});
 
-export default await server.run();
-
-export type AppType = typeof server;
+export type AppType = typeof app;

package/templates/ecom/src/tools/render-carousel.ts

@@ -1,73 +1,11 @@
 import { z } from "zod";
+import { getProducts } from "../catalog/index.js";
 import { CAROUSEL_MAX_SIZE, CAROUSEL_RANGE } from "../config.js";
-import {
-  type Attribute,
-  AttributeSchema,
-  type Price,
-  PriceSchema,
-} from "../types.js";
+import { PriceSchema, type Product, SpecSchema } from "../types.js";
 
 // The `render-carousel` tool: takes the IDs the model curated and returns the
-// matching products for the carousel view to render.
-// Everything this tool needs lives in this file.
-
-// ---------------------------------------------------------------------------
-// Product model
-// ---------------------------------------------------------------------------
-// Model: variant-as-full-product. Each `Variant` is a complete, buyable product
-// (its own title, price, media). A `Product` ties sibling variants together and
-// declares the axes (`Option`s) they vary on. A product with no variations is
-// just a product with a single variant and no options.
-
-// One selectable value on an axis, e.g. the "Black" choice on the "Color" axis.
-type OptionValue = {
-  id: string; // stable key referenced by Variant.selection, e.g. "black"
-  label: string; // shown to the user, e.g. "Black"
-  media?: string; // optional swatch / image representing this value
-};
-
-// A variation axis the variants differ on, e.g. Color or Size.
-type Option = {
-  id: string; // stable key, used as a key in Variant.selection, e.g. "color"
-  label: string; // shown to the user, e.g. "Color"
-  values: OptionValue[]; // in display order
-};
-
-// Display fields shared by a Variant and by a product's `card`.
-type Meta = {
-  title: string;
-  description?: string;
-  price?: Price;
-  media: string[]; // images for this item; media[0] is the primary/cover
-  url?: string; // link to this item's external product page
-  outOfStock?: boolean; // true = not purchasable
-  // Facts to display: spec rows, promo labels, etc.
-  attributes: Attribute[];
-};
-
-// One buyable product: full display Meta plus which value it takes on each axis.
-export type Variant = Meta & {
-  id: string; // SKU / article number; unique within the catalog
-  // The chosen value per axis: keys are Option.id, values are OptionValue.id.
-  // e.g. { color: "black", size: "40" }
-  selection: Record<string, string>;
-};
-
-// A product: one carousel card backed by one or more variants and the axes they
-// vary on (none for a single-variant product).
-export type Product = {
-  id: string; // stable product key
-  options: Option[]; // the axes the variants vary on
-  // Only the variants that actually exist. A missing combination (e.g. no
-  // { color: "black", size: "40" }) is simply absent from this list — that is how
-  // contingent variations are expressed. Derive the selectable values for an axis
-  // by filtering this list on the choices already made.
-  variants: Variant[];
-  // The product's carousel card. Surfaced both in the carousel (the view
-  // renders it) and to the model (structuredContent is projected from it).
-  // How you build it depends on your mapping strategy: see getProducts.
-  card: Meta;
-};
+// matching products for the carousel view to render. Data access lives in
+// `src/catalog/`; everything else this tool needs lives in this file.
 
 // ---------------------------------------------------------------------------
 // Input
@@ -101,37 +39,18 @@ const outputSchema = {
         description: z.string().optional(),
         price: PriceSchema.optional(),
         outOfStock: z.boolean(),
-        attributes: z
-          .array(AttributeSchema)
-          .describe("Product facts (specs, promo labels…)."),
+        specs: z
+          .array(SpecSchema)
+          .describe("Product-specific facts (material, dimensions, care…)."),
       }),
     )
     .describe(
-      "The products shown in the carousel, in display order. For your reference only — to curate, compare, and answer follow-ups. Ground every claim in this data; never invent attributes.",
+      "The products shown in the carousel, in display order. For your reference only — to curate, compare, and answer follow-ups. Ground every claim in this data; never invent facts.",
     ),
 };
 
 type RenderOutput = z.infer<z.ZodObject<typeof outputSchema>>;
 
-// ---------------------------------------------------------------------------
-// Data access
-// ---------------------------------------------------------------------------
-
-async function getProducts(_ids: string[]): Promise<Product[]> {
-  // @todo: fetch each id from your product API / DB and map the results into
-  // `Product`s (rename `_ids` -> `ids` once you use it).
-  //
-  // First decide your mapping strategy — it depends on your catalog:
-  //   - no variants (simple products): one `Product`, a single variant, card = that variant, options: [],
-  //   - grouped: one `Product` per product; `card` = union of its variants, one picture per requested variant
-  //   - one card per requested variant: `card` = that variant
-  // Either way, set `variants` to ALL variants the source returns for the product;
-  // the detail view reads them so the client can switch variant.
-  //
-  // Returns [] for now, so the carousel is empty.
-  return [];
-}
-
 // ---------------------------------------------------------------------------
 // Mapping: trim each product's `card` and `options` into the model-facing
 // grounding (outputSchema), dropping presentational fields (media, url). The
@@ -162,7 +81,7 @@ function toStructuredContent(products: Product[]): RenderOutput {
       price: card.price,
       outOfStock: card.outOfStock ?? false,
       options,
-      attributes: card.attributes,
+      specs: card.specs,
     });
   }
 
@@ -182,7 +101,7 @@ export const renderCarouselDefinition = {
 Display the products you curated as an inline carousel for the client.
 
 ## When to call
-Call this AFTER searching and curating, and BEFORE writing your recommendation. Do not describe the products in text first; the carousel shows them. Stay silent until it has rendered, then speak.
+Call this AFTER searching and curating, and BEFORE writing your recommendation. Avoid describing the products in text first since the carousel shows them.
 
 ## What to pass
 Pass the IDs of the ${CAROUSEL_RANGE} products you chose, in display order (most relevant first). Order is significant: the carousel shows them in this exact order and your recommendation must follow the same sequence. Pass distinct products, not several variants of the same one; the detail view lets the client explore a product's variants (colors, sizes, and so on).
@@ -191,7 +110,7 @@ Pass the IDs of the ${CAROUSEL_RANGE} products you chose, in display order (most
 Recommend in carousel order so the client can follow along. The cards already show image, title, price, and key facts, so do not repeat them: add useful analysis tied to the client's need. Suggest a refinement the client has not addressed yet (from the available filters), never one they already used.
 
 ## Accuracy
-Use only the data returned for each product. Never invent attributes, materials, or availability. If the client asks about something not present, open that product's detail or search again before answering.`,
+Use only the data returned for each product. Never invent facts, materials, or availability. If the client asks about something not present, open that product's detail or search again before answering.`,
   annotations: {
     readOnlyHint: true,
     openWorldHint: false,

package/templates/ecom/src/tools/search-products.ts

@@ -1,15 +1,17 @@
 import { z } from "zod";
+import { search } from "../catalog/index.js";
 import {
   CAROUSEL_MAX_SIZE,
   CAROUSEL_RANGE,
   MIN_SEARCH_ITERATIONS,
 } from "../config.js";
-import { AttributeSchema, PriceSchema } from "../types.js";
+import { PriceSchema, type SearchResult, SpecSchema } from "../types.js";
 
 // The `search-products` tool: keyword + filters in, matching products out as
 // structured output for the model. It has NO view — include only what the model
 // needs to curate (ids + properties), never presentational data (images, media);
-// render-carousel handles that. Everything this tool needs lives in this file.
+// render-carousel handles that. Data access lives in `src/catalog/`; everything
+// else this tool needs lives in this file.
 
 // ---------------------------------------------------------------------------
 // Input
@@ -21,10 +23,8 @@ const inputSchema = {
   keyword: z.string().describe(
     `\
 Short noun phrases extracted from conversational input. Never pass full sentences. \
-ALWAYS use the singular form, not the plural. \
 Include color, material, and style descriptors for accuracy. \
-For vague gift or occasion queries without a clear product type, use broad category terms. \
-Preserve the existing keyword across filter refinements; only replace when the user makes a completely different request.`,
+For vague gift or occasion queries without a clear product type, use broad category terms.`,
   ),
 
   // @todo: set the sort options your backend supports (or remove).
@@ -41,7 +41,7 @@ Preserve the existing keyword across filter refinements; only replace when the u
     ),
 };
 
-type SearchInput = z.infer<z.ZodObject<typeof inputSchema>>;
+export type SearchInput = z.infer<z.ZodObject<typeof inputSchema>>;
 
 // ---------------------------------------------------------------------------
 // Output — model-facing grounding, returned in structuredContent.
@@ -56,9 +56,12 @@ const productSchema = z.object({
     .boolean()
     .optional()
     .describe("True when the product is not purchasable."),
-  attributes: z
-    .array(AttributeSchema)
-    .describe("Facts to curate on (specs, materials, promo labels…)."),
+  specs: z
+    .array(SpecSchema)
+    .describe("Product-specific facts to curate on (material, dimensions…)."),
+
+  // @todo: Add whatever custom fields the model should curate on as real types,
+  // not `specs` strings (e.g. `rating`, `discountPct`, `badges`).
 });
 
 const outputSchema = {
@@ -79,17 +82,29 @@ const outputSchema = {
 type SearchOutput = z.infer<z.ZodObject<typeof outputSchema>>;
 
 // ---------------------------------------------------------------------------
-// Data access
+// Mapping: project each product's `card` into the model-facing grounding
+// (outputSchema), dropping presentational fields (media, url).
+// @todo: choose what the model sees per product. Grounding only: the model
+// curates on facts, so presentational data never belongs here.
 // ---------------------------------------------------------------------------
 
-function search(_input: SearchInput): SearchOutput {
-  // @todo: plug in your product API / DB. Query it with the input params and map
-  // each result into `products` below. `pages` and `totalHits` are optional.
-  return {
-    products: [], // { id: string; properties: { name: PropertyName; value: string[] }[] }[]
-    pages: { current: 1, total: 1 },
-    totalHits: 0,
-  };
+function toStructuredContent({
+  products,
+  pages,
+  totalHits,
+}: SearchResult): SearchOutput {
+  const results: SearchOutput["products"] = [];
+  for (const { id, card } of products) {
+    results.push({
+      id,
+      title: card.title,
+      description: card.description,
+      price: card.price,
+      outOfStock: card.outOfStock,
+      specs: card.specs,
+    });
+  }
+  return { products: results, pages, totalHits };
 }
 
 // ---------------------------------------------------------------------------
@@ -97,7 +112,7 @@ function search(_input: SearchInput): SearchOutput {
 // themselves ride in structuredContent; this text carries NO result data.
 // @todo: customize the NEXT STEPS guidance below for your flow (keep searching
 // vs. curate and render). Remind the model to ground claims in the structured
-// results and never invent attributes.
+// results and never invent facts.
 // ---------------------------------------------------------------------------
 
 function narrate({ products }: SearchOutput): string {
@@ -142,15 +157,14 @@ export const searchProductsDefinition = {
 Search the product catalog. Handles any query: specific products, broad categories, gifts, occasions, or open discovery.
 Never assume a category is unavailable: always search before responding.
 
-The response is data only: a list of matching products (name, ID, price, description, and any product-specific attributes) plus pagination and the available filters. The raw results are for your eyes only: the client never sees them.
+The response is data only: a list of matching products (name, ID, price, description, and any product-specific facts) plus pagination and the available filters. The raw results are for your eyes only: the client never sees them.
 
-NEVER describe or characterize the raw results to the client: do not mention how many there are, what categories they fall into, or that they look off-topic. While searching, stay silent: do not narrate what you are doing, announce searches, or report progress between tool calls. Speak only once the carousel is rendered.
+NEVER describe or characterize the raw results to the client: do not mention how many there are, what categories they fall into, or that they look off-topic.
 
 Act on the response as follows:
 
-- FIRST SEARCH: use the keyword only (plus sort if needed). Read the available filters in the response; these are the only valid filter options for follow-ups.
-- REFINEMENT: if the user's intent matches an available filter, apply it. If it doesn't match any filter, start a new keyword search.
-- ITERATE: a single search is never enough. Run several searches (${MIN_SEARCH_ITERATIONS} minimum) before rendering: vary the keyword, apply a filter, or page deeper, and compare results across them. Quality comes from this multi-call exploration; one call then render gives shallow results.
+- FIRST SEARCH: use keywords only (plus sort if needed).
+- ITERATE: a single search is not always enough. Run several searches (${MIN_SEARCH_ITERATIONS} minimum) before rendering: vary the keyword, apply a filter, or page deeper, and compare results across them. Quality comes from this multi-call exploration; one call then render gives shallow results.
 - CURATION: read results and pick the best matches for the client's intent, grounding your choice in each product's description. If zero results, broaden the keyword or relax filters and search again: do NOT call render-carousel. If fewer than 3 results and the user didn't ask for a specific product, search again with broader terms. Only after exploring across several searches, call render-carousel with the selected IDs.
 - PRESENT: Once you have ${CAROUSEL_RANGE} distinct, relevant products, call render-carousel with their IDs. Recommend ONLY AFTER the carousel displays, in carousel order.
 
@@ -172,8 +186,8 @@ The sweet spot is ${CAROUSEL_RANGE} products.
   outputSchema,
 };
 
-export function searchProductsHandler(input: SearchInput) {
-  const results = search(input);
+export async function searchProductsHandler(input: SearchInput) {
+  const results = toStructuredContent(await search(input));
   return {
     structuredContent: results,
     content: [{ type: "text" as const, text: narrate(results) }],

package/templates/ecom/src/types.ts

@@ -6,8 +6,82 @@ export const PriceSchema = z.object({
 });
 export type Price = z.infer<typeof PriceSchema>;
 
-export const AttributeSchema = z.object({
-  name: z.string(),
+// A product-specific fact (an objective spec: material, dimensions, capacity,
+// care…). `label` is optional so a fact can be a bare value (e.g. "Waterproof").
+export const SpecSchema = z.object({
+  label: z.string().optional(),
   value: z.string(),
 });
-export type Attribute = z.infer<typeof AttributeSchema>;
+export type Spec = z.infer<typeof SpecSchema>;
+
+// ---------------------------------------------------------------------------
+// Product model — what the catalog providers in `src/catalog/` return and the
+// views render. Model: variant-as-full-product. Each `Variant` is a complete,
+// buyable product (its own title, price, media). A `Product` ties sibling
+// variants together and declares the axes (`Option`s) they vary on. A product
+// with no variations is just a product with a single variant and no options.
+// ---------------------------------------------------------------------------
+
+// One selectable value on an axis, e.g. the "Black" choice on the "Color" axis.
+type OptionValue = {
+  id: string; // stable key referenced by Variant.selection, e.g. "black"
+  label: string; // shown to the user, e.g. "Black"
+  media?: string; // optional swatch / image representing this value
+};
+
+// A variation axis the variants differ on, e.g. Color or Size.
+export type Option = {
+  id: string; // stable key, used as a key in Variant.selection, e.g. "color"
+  label: string; // shown to the user, e.g. "Color"
+  values: OptionValue[]; // in display order
+};
+
+// Display fields shared by a Variant and by a product's `card`.
+type Meta = {
+  title: string;
+  description?: string;
+  price?: Price;
+  media: string[]; // images for this item; media[0] is the primary/cover
+  url?: string; // link to this item's external product page
+  outOfStock?: boolean; // true = not purchasable
+  // Objective, product-specific facts (material, dimensions, capacity, care…),
+  // rendered as-is. Each fact's label is optional.
+  specs: Spec[];
+
+  // @todo: Add whatever custom fields the carousel should render as real types
+  // (e.g. `rating` → stars, `discountPct` → badge, `badges` → chips).
+};
+
+// One buyable product: full display Meta plus which value it takes on each axis.
+export type Variant = Meta & {
+  id: string; // SKU / article number; unique within the catalog
+  // The chosen value per axis: keys are Option.id, values are OptionValue.id.
+  // e.g. { color: "black", size: "40" }
+  selection: Record<string, string>;
+};
+
+// A product: one carousel card backed by one or more variants and the axes they
+// vary on (none for a single-variant product).
+export type Product = {
+  id: string; // stable product key
+  // The axes the variants vary on, in display order. Order is semantic: the
+  // detail picker narrows availability top-down (each axis constrained by the
+  // ones before it), so put the imagery-driving axis (usually color) first.
+  options: Option[];
+  // Only the variants that actually exist. A missing combination (e.g. no
+  // { color: "black", size: "40" }) is simply absent from this list — that is how
+  // contingent variations are expressed. Derive the selectable values for an axis
+  // by filtering this list on the choices already made.
+  variants: Variant[];
+  // The product's carousel card. Surfaced both in the carousel (the view
+  // renders it) and to the model (structuredContent is projected from it).
+  card: Meta;
+};
+
+// What a catalog provider's `search` returns. `pages` and `totalHits` are
+// optional: not every backend reports them.
+export type SearchResult = {
+  products: Product[];
+  pages?: { current: number; total: number };
+  totalHits?: number;
+};