create-skybridge 0.0.0-dev.06d207f → 0.0.0-dev.06f809c

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

@@ -0,0 +1,185 @@
+import { z } from "zod";
+import {
+  CAROUSEL_MAX_SIZE,
+  CAROUSEL_RANGE,
+  MIN_SEARCH_ITERATIONS,
+} from "../config.js";
+import { PriceSchema, 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.
+
+// ---------------------------------------------------------------------------
+// Input
+// ---------------------------------------------------------------------------
+
+const inputSchema = {
+  // @todo: tune this guidance to your catalog's vocabulary. The model reads
+  // it to turn conversational input into a good keyword.
+  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.`,
+  ),
+
+  // @todo: set the sort options your backend supports (or remove).
+  sort: z.enum(["price-asc", "price-desc"]).optional().describe("Sort order."),
+
+  // @todo: declare the filters your catalog supports. Add one param per
+  // facet (category, color, size...), each optional so the model only sends
+  // what the user asked for. `priceRange` below is just an example, remove it.
+  priceRange: z
+    .string()
+    .optional()
+    .describe(
+      "Price range in dollars. Format: 'min-max' e.g. '0-500', '1000-2000'.",
+    ),
+};
+
+type SearchInput = z.infer<z.ZodObject<typeof inputSchema>>;
+
+// ---------------------------------------------------------------------------
+// Output — model-facing grounding, returned in structuredContent.
+// ---------------------------------------------------------------------------
+
+const productSchema = z.object({
+  id: z.string().describe("Stable product ID; pass to render-carousel."),
+  title: z.string(),
+  description: z.string().optional(),
+  price: PriceSchema.optional(),
+  outOfStock: z
+    .boolean()
+    .optional()
+    .describe("True when the product is not purchasable."),
+  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 = {
+  products: z.array(productSchema).describe("Matching products, sorted."),
+  pages: z
+    .object({
+      current: z.number(),
+      total: z.number(),
+    })
+    .optional()
+    .describe("Pagination: current page and total page count."),
+  totalHits: z
+    .number()
+    .optional()
+    .describe("Total matching products across all pages."),
+};
+
+type SearchOutput = z.infer<z.ZodObject<typeof outputSchema>>;
+
+// ---------------------------------------------------------------------------
+// Data access
+// ---------------------------------------------------------------------------
+
+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,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Narration — framing + next-step instructions for the model. The products
+// 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 facts.
+// ---------------------------------------------------------------------------
+
+function narrate({ products }: SearchOutput): string {
+  const size = products.length;
+
+  if (size === 0) {
+    return `\
+No products found.
+
+NEXT STEP: Broaden the keyword or relax filters, then search again.`;
+  }
+
+  if (size < CAROUSEL_MAX_SIZE) {
+    return `\
+Only a few results.
+
+NEXT STEPS:
+1. If the client asked for a specific product by name, these are fine: curate and call render-carousel with the selected IDs.
+2. Otherwise, search again with broader terms before rendering.`;
+  }
+
+  return `\
+Enough results to present.
+
+NEXT STEPS:
+1. Curate the best matches for the client's intent from the structured results.
+2. Write your recommendation mentioning the selected products.
+3. Call render-carousel with the selected IDs.`;
+}
+
+// ---------------------------------------------------------------------------
+// Tool (registered from server.ts to keep the typed tool chain intact)
+// ---------------------------------------------------------------------------
+
+export const searchProductsDefinition = {
+  name: "search-products" as const,
+
+  // @todo: describe YOUR catalog and how the agent should search and curate
+  // it. This is the model's main guide: be specific about your categories,
+  // the multi-call search loop, and when to render vs. keep searching.
+  description: `\
+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 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.
+
+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.
+- 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.
+
+The sweet spot is ${CAROUSEL_RANGE} products.
+`,
+  annotations: {
+    readOnlyHint: true,
+    openWorldHint: false,
+    destructiveHint: false,
+  },
+
+  // @todo: customize the status messages shown in ChatGPT while the tool runs.
+  _meta: {
+    "openai/toolInvocation/invoking": "Searching the catalog",
+    "openai/toolInvocation/invoked": "Searched the catalog",
+  },
+
+  inputSchema,
+  outputSchema,
+};
+
+export function searchProductsHandler(input: SearchInput) {
+  const results = search(input);
+  return {
+    structuredContent: results,
+    content: [{ type: "text" as const, text: narrate(results) }],
+    isError: false,
+  };
+}

package/templates/ecom/src/types.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+
+export const PriceSchema = z.object({
+  amount: z.number(),
+  currency: z.string(),
+});
+export type Price = z.infer<typeof PriceSchema>;
+
+// 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 Spec = z.infer<typeof SpecSchema>;

package/templates/ecom/src/views/carousel/detail/detail.css.ts

@@ -0,0 +1,115 @@
+import { style } from "@vanilla-extract/css";
+import { colors, primitives } from "../../../design/tokens";
+
+// Two-column breakpoint. Layout is driven by the pane's own width (container
+// query), never the viewport, so a phone and a resized desktop pane agree.
+const TWO_COLUMN_MIN_WIDTH = "560px";
+
+export const detail = style({
+  containerType: "inline-size",
+  padding: primitives.space.s,
+  // Clear the notch / home indicator when the page bleeds to the screen edge.
+  paddingBottom: `calc(${primitives.space.s} + env(safe-area-inset-bottom))`,
+});
+
+// Product / variant id, idiomatically top-right. @todo: reposition (drop the
+// right align, or move it in the JSX) or remove it.
+export const reference = style({
+  textAlign: "right",
+  color: colors.content.subtle,
+  marginBottom: primitives.space["3xs"],
+});
+
+// Single column by default; two columns (gallery | info) once the pane is wide.
+export const grid = style({
+  display: "flex",
+  flexDirection: "column",
+  gap: primitives.space.s,
+  maxWidth: "1099px",
+  marginInline: "auto",
+  "@container": {
+    [`(min-width: ${TWO_COLUMN_MIN_WIDTH})`]: {
+      display: "grid",
+      // `minmax(0, 1fr)` (not `1fr`) lets a column shrink below its content's
+      // intrinsic width, so a chip row scrolls/wraps instead of blowing out.
+      gridTemplateColumns: "minmax(0, 1fr) minmax(0, 1fr)",
+      gridTemplateAreas: '"gallery info"',
+      alignItems: "start",
+    },
+  },
+});
+
+export const galleryCell = style({
+  "@container": {
+    [`(min-width: ${TWO_COLUMN_MIN_WIDTH})`]: {
+      gridArea: "gallery",
+      position: "sticky",
+      top: primitives.space.s,
+    },
+  },
+});
+
+// The info column owns all inter-section spacing; sections set no outer margin.
+export const info = style({
+  display: "flex",
+  flexDirection: "column",
+  gap: primitives.space.xs,
+  "@container": {
+    [`(min-width: ${TWO_COLUMN_MIN_WIDTH})`]: { gridArea: "info" },
+  },
+});
+
+export const title = style({ color: colors.content.intense });
+
+export const price = style({ color: colors.content.intense });
+
+export const oos = style({ color: colors.common.error });
+
+// Product facts as a simple list: one line per fact, "label: value" (or just
+// the value when unlabeled). marginTop separates it from the section heading.
+// @todo: reshape freely (a table, grouped sections, inline chips…)
+export const specList = style({
+  display: "flex",
+  flexDirection: "column",
+  gap: primitives.space["3xs"],
+  marginTop: primitives.space["3xs"],
+  marginBottom: 0,
+});
+
+// One fact on a line: "label:" then value.
+export const specRow = style({
+  display: "flex",
+  gap: primitives.space["4xs"],
+});
+
+export const specLabel = style({
+  margin: 0,
+  color: colors.content.subtle,
+});
+
+export const specValue = style({
+  margin: 0,
+  color: colors.content.intense,
+});
+
+// Primary CTA. @todo: tune to your brand; add a secondary action beside it
+// (ask-the-assistant, contact) as a per-catalog extension.
+export const cta = style({
+  minHeight: "44px",
+  padding: `${primitives.space["3xs"]} ${primitives.space.s}`,
+  borderRadius: primitives.radius.m,
+  border: "none",
+  backgroundColor: colors.common.accent,
+  color: colors.content.invertIntense,
+  fontFamily: primitives.font.family.primary,
+  fontSize: primitives.font.size.m,
+  fontWeight: primitives.font.weight.medium,
+  cursor: "pointer",
+  selectors: {
+    "&:disabled": {
+      backgroundColor: colors.surface.intense,
+      color: colors.content.subtle,
+      cursor: "not-allowed",
+    },
+  },
+});

package/templates/ecom/src/views/carousel/detail/detail.stories.tsx

@@ -0,0 +1,115 @@
+import type { Product } from "../../../tools/render-carousel.js";
+import { DetailView } from "./index";
+
+function shot(fill: string) {
+  return `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='400' height='400'%3E%3Crect width='400' height='400' fill='%23${fill}'/%3E%3Ccircle cx='200' cy='200' r='110' fill='%23ffffff' fill-opacity='0.5'/%3E%3C/svg%3E`;
+}
+
+// A long media set (primary shot + several accents) so the desktop thumbnail
+// rail is taller than the image and overflows past its bottom.
+const ACCENT_FILLS = [
+  "c9d4f5",
+  "f5d4c9",
+  "d4f5c9",
+  "f5f0c9",
+  "e0c9f5",
+  "c9f5f0",
+  "f5c9e0",
+  "d9d9d9",
+];
+
+function galleryMedia(primaryFill: string): string[] {
+  const media = [shot(primaryFill)];
+  for (const fill of ACCENT_FILLS) {
+    media.push(shot(fill));
+  }
+  return media;
+}
+
+const DESCRIPTION =
+  "A relaxed-fit jacket in water-repellent cotton.\n\nDropped shoulders, a two-way zip, and ribbed cuffs. Fully lined, with two zip pockets at the front and one inside.";
+
+// Two axes with a sparse variant set: {black,M}, {black,L}, {sand,M} exist —
+// so choosing "Sand" disables "L".
+function jacket(
+  id: string,
+  color: string,
+  colorLabel: string,
+  size: string,
+): Product["variants"][number] {
+  return {
+    id,
+    selection: { color, size },
+    title: `Field jacket — ${colorLabel}`,
+    description: DESCRIPTION,
+    price: { amount: color === "sand" ? 249 : 229, currency: "EUR" },
+    media: galleryMedia(color === "sand" ? "d8c7a8" : "2b2b2b"),
+    url: "https://example.com/jacket",
+    specs: [
+      { label: "Material", value: "Water-repellent cotton" },
+      { label: "Fit", value: "Relaxed" },
+      { value: "Machine washable" }, // label-less fact (renders value only)
+    ],
+  };
+}
+
+const PRODUCT: Product = {
+  id: "field-jacket",
+  options: [
+    {
+      id: "color",
+      label: "Color",
+      values: [
+        { id: "black", label: "Black", media: shot("2b2b2b") },
+        { id: "sand", label: "Sand", media: shot("d8c7a8") },
+      ],
+    },
+    {
+      id: "size",
+      label: "Size",
+      values: [
+        { id: "m", label: "M" },
+        { id: "l", label: "L" },
+      ],
+    },
+  ],
+  variants: [
+    jacket("fj-black-m", "black", "Black", "m"),
+    jacket("fj-black-l", "black", "Black", "l"),
+    jacket("fj-sand-m", "sand", "Sand", "m"),
+  ],
+  card: {
+    title: "Field jacket",
+    price: { amount: 229, currency: "EUR" },
+    media: [shot("2b2b2b")],
+    specs: [],
+  },
+};
+
+export const Default = () => <DetailView product={PRODUCT} />;
+
+// Single-variant product: no picker, buyable immediately.
+const SIMPLE: Product = {
+  id: "tote",
+  options: [],
+  variants: [
+    {
+      id: "tote",
+      selection: {},
+      title: "Canvas tote",
+      description: "A sturdy everyday canvas tote.",
+      price: { amount: 39, currency: "EUR" },
+      media: [shot("e1e1e1")],
+      url: "https://example.com/tote",
+      specs: [{ label: "Material", value: "Canvas" }],
+    },
+  ],
+  card: {
+    title: "Canvas tote",
+    price: { amount: 39, currency: "EUR" },
+    media: [shot("e1e1e1")],
+    specs: [],
+  },
+};
+
+export const SingleVariant = () => <DetailView product={SIMPLE} />;

package/templates/ecom/src/views/carousel/detail/index.tsx

@@ -0,0 +1,240 @@
+import { useEffect, useState } from "react";
+import { useOpenExternal, useSetOpenInAppUrl, useUser } from "skybridge/web";
+import { ExpandableText } from "../../../components/expandable-text";
+import { ImageGallery } from "../../../components/image-gallery";
+import { VariantPicker } from "../../../components/variant-picker";
+import { sprinkles, text } from "../../../design/tokens";
+import { type Labels, useLabels } from "../../../i18n";
+import { cx } from "../../../lib/cx";
+import { formatPrice } from "../../../lib/format";
+import {
+  initialSelection,
+  resolveVariant,
+  type Selection,
+} from "../../../lib/variants.js";
+import type { Product } from "../../../tools/render-carousel.js";
+import * as styles from "./detail.css";
+
+// Price to show: the resolved variant's price, else the range across variants
+// (or a single price when they agree), else the card price, else a fallback.
+function priceText(
+  product: Product,
+  variantPrice: Product["card"]["price"],
+  locale: string,
+  labels: Labels,
+): string {
+  if (variantPrice) {
+    return formatPrice(variantPrice, locale);
+  }
+  const amounts: number[] = [];
+  let currency = "";
+  for (const variant of product.variants) {
+    if (variant.price) {
+      amounts.push(variant.price.amount);
+      currency = variant.price.currency;
+    }
+  }
+  if (amounts.length > 0) {
+    const min = Math.min(...amounts);
+    const max = Math.max(...amounts);
+    if (min === max) {
+      return formatPrice({ amount: min, currency }, locale);
+    }
+    return `${formatPrice({ amount: min, currency }, locale)} – ${formatPrice({ amount: max, currency }, locale)}`;
+  }
+  if (product.card.price) {
+    return formatPrice(product.card.price, locale);
+  }
+  return labels.priceOnRequest;
+}
+
+// data-llm narrates the variant the user is currently looking at. The full
+// product spec (every variant) is pushed to view state by the carousel
+// orchestrator, so the model can answer beyond what is on screen; this stays
+// scoped to the visible selection.
+function grounding(
+  product: Product,
+  title: string,
+  price: string,
+  selection: Selection,
+  outOfStock: boolean,
+  labels: Labels,
+): string {
+  const parts = [`The user is viewing "${title}" (product id: ${product.id}).`];
+  const chosen: string[] = [];
+  for (const option of product.options) {
+    let label = "not selected";
+    const valueId = selection[option.id];
+    for (const value of option.values) {
+      if (value.id === valueId) {
+        label = value.label;
+        break;
+      }
+    }
+    chosen.push(`${option.label}: ${label}`);
+  }
+  if (chosen.length > 0) {
+    parts.push(`Selected — ${chosen.join(", ")}.`);
+  }
+  parts.push(`Price: ${price}.`);
+  if (outOfStock) {
+    parts.push(labels.outOfStock);
+  }
+  return parts.join(" ");
+}
+
+/**
+ * Product detail view, rendered fullscreen over the carousel (see the carousel
+ * orchestrator). Reads a single product from the payload already in `_meta`;
+ * does no fetch. Option choices resolve against the product's sparse variant
+ * list in-place (no remount).
+ */
+export function DetailView({ product }: { product: Product }) {
+  const { locale } = useUser();
+  const labels = useLabels();
+  const openExternal = useOpenExternal();
+  const setOpenInAppUrl = useSetOpenInAppUrl();
+  const [selection, setSelection] = useState<Selection>(() =>
+    initialSelection(product),
+  );
+
+  const variant = resolveVariant(product, selection);
+  // Fall back to the card for display fields until a variant resolves.
+  const displayTitle = variant?.title ?? product.card.title;
+  const description = variant?.description ?? product.card.description;
+  const media = variant?.media.length ? variant.media : product.card.media;
+  const specs = variant?.specs ?? product.card.specs;
+  const outOfStock = variant?.outOfStock ?? product.card.outOfStock ?? false;
+  const url = variant?.url ?? product.card.url;
+  // The shown item's id: the resolved variant's SKU, else the product id.
+  const reference = variant?.id ?? product.id;
+  // @todo: read any custom Meta fields you added the same way (variant first,
+  // then card), e.g. `const rating = variant?.rating ?? product.card.rating;`,
+  // then render them in the agreed spot (rating by the title, discount by the
+  // price, badges as chips…).
+
+  const price = priceText(product, variant?.price, locale, labels);
+  // Buy CTA is enabled only once a variant resolves and carries a real link
+  // (an empty url would leave the button enabled but dead).
+  const canBuy = variant != null && Boolean(url);
+
+  // Point the host's fullscreen "Open in app" affordance at the selected
+  // variant's page. Apps-SDK only; MCP Apps hosts reject, so ignore that.
+  useEffect(() => {
+    if (url) {
+      setOpenInAppUrl(url).catch(() => {});
+    }
+  }, [url, setOpenInAppUrl]);
+
+  return (
+    <div
+      className={styles.detail}
+      data-llm={grounding(
+        product,
+        displayTitle,
+        price,
+        selection,
+        outOfStock,
+        labels,
+      )}
+    >
+      {/* Product / variant reference, idiomatically top-right. @todo: move it
+          (e.g. into the info column under the title) or drop it; restyle in
+          detail.css.ts (`reference`). */}
+      <p className={cx(text({ style: "bodyS" }), styles.reference)}>
+        {labels.reference} {reference}
+      </p>
+
+      <div className={styles.grid}>
+        <div className={styles.galleryCell}>
+          {media.length > 0 ? (
+            // Key on the media set so switching to a variant with different
+            // images remounts the gallery fresh (index reset to the first image).
+            <ImageGallery
+              key={media.join("|")}
+              media={media}
+              alt={displayTitle}
+            />
+          ) : null}
+        </div>
+
+        <div className={styles.info}>
+          <h1
+            className={cx(
+              text({ style: "headingS", weight: "medium" }),
+              styles.title,
+            )}
+          >
+            {displayTitle}
+          </h1>
+
+          <p className={cx(text({ style: "headingS" }), styles.price)}>
+            {price}
+          </p>
+
+          {outOfStock ? (
+            <p className={cx(text({ style: "bodyS" }), styles.oos)}>
+              {labels.outOfStock}
+            </p>
+          ) : null}
+
+          <VariantPicker
+            product={product}
+            selection={selection}
+            onChange={setSelection}
+          />
+
+          {description ? <ExpandableText>{description}</ExpandableText> : null}
+
+          <button
+            type="button"
+            className={cx(styles.cta, sprinkles({ mt: "3xs" }))}
+            disabled={!canBuy}
+            onClick={canBuy && url ? () => openExternal(url) : undefined}
+          >
+            {variant ? labels.viewOnSite : labels.selectOptions}
+          </button>
+
+          {/* Product facts as a simple list, after the CTA: one "label: value"
+              line per fact (label-less facts show the value alone). This is the
+              visual treatment only; the full spec is already in view state for
+              the model (see the carousel orchestrator), so restyling or dropping
+              it never hides facts from the assistant. @todo: pick the shape that
+              best presents your specs: this list (default), a two-column table,
+              grouped sections, inline chips, etc. */}
+          {specs.length > 0 ? (
+            <section>
+              <h2 className={text({ style: "labelM", weight: "medium" })}>
+                {labels.specifications}
+              </h2>
+              <dl className={styles.specList}>
+                {specs.map((spec) => (
+                  <div
+                    key={`${spec.label ?? ""}:${spec.value}`}
+                    className={styles.specRow}
+                  >
+                    {spec.label ? (
+                      <dt
+                        className={cx(
+                          text({ style: "bodyS" }),
+                          styles.specLabel,
+                        )}
+                      >
+                        {spec.label}:
+                      </dt>
+                    ) : null}
+                    <dd
+                      className={cx(text({ style: "bodyS" }), styles.specValue)}
+                    >
+                      {spec.value}
+                    </dd>
+                  </div>
+                ))}
+              </dl>
+            </section>
+          ) : null}
+        </div>
+      </div>
+    </div>
+  );
+}