create-skybridge 0.0.0-dev.994f77c → 0.0.0-dev.995023d

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

@@ -1,75 +1,11 @@
 import { z } from "zod";
+import { getProducts } from "../catalog/index.js";
 import { CAROUSEL_MAX_SIZE, CAROUSEL_RANGE } from "../config.js";
-import { type Price, PriceSchema, type Spec, SpecSchema } 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
-  // 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).
-  // 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
@@ -115,26 +51,6 @@ const outputSchema = {
 
 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. Order `options`
-  // with the imagery-driving axis first (see the Product type: order is semantic).
-  //
-  // 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
@@ -185,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).

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 { PriceSchema, SpecSchema } 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.
@@ -82,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 };
 }
 
 // ---------------------------------------------------------------------------
@@ -147,13 +159,12 @@ 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.
+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.
 
@@ -175,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

@@ -13,3 +13,75 @@ export const SpecSchema = z.object({
   value: z.string(),
 });
 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;
+};

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

@@ -7,6 +7,8 @@ const TWO_COLUMN_MIN_WIDTH = "560px";
 
 export const detail = style({
   containerType: "inline-size",
+  maxHeight: "100dvh",
+  overflowY: "auto",
   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))`,

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

@@ -1,4 +1,4 @@
-import type { Product } from "../../../tools/render-carousel.js";
+import type { Product } from "../../../types.js";
 import { DetailView } from "./index";
 
 function shot(fill: string) {
@@ -56,7 +56,14 @@ function jacket(
     outOfStock,
     specs: [
       { label: "Material", value: "Water-repellent cotton" },
+      { label: "Lining", value: "Recycled polyester" },
       { label: "Fit", value: "Relaxed" },
+      { label: "Closure", value: "Two-way zip" },
+      { label: "Pockets", value: "Two zip front, one inside" },
+      { label: "Collar", value: "Stand-up" },
+      { label: "Cuffs", value: "Ribbed" },
+      { label: "Weight", value: "780 g" },
+      { label: "Origin", value: "Made in Portugal" },
       { value: "Machine washable" }, // label-less fact (renders value only)
     ],
   };

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

@@ -12,7 +12,7 @@ import {
   resolveVariant,
   type Selection,
 } from "../../../lib/variants.js";
-import type { Product, Variant } from "../../../tools/render-carousel.js";
+import type { Product, Variant } from "../../../types.js";
 import * as styles from "./detail.css";
 
 // Price to show: the resolved variant's price, else the range across variants

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

@@ -20,8 +20,7 @@ import { sprinkles } from "../../design/tokens";
 import { useToolInfo } from "../../helpers.js";
 import { useLabels } from "../../i18n";
 import { formatPrice } from "../../lib/format";
-import type { Product } from "../../tools/render-carousel.js";
-import type { Price, Spec } from "../../types.js";
+import type { Price, Product, Spec } from "../../types.js";
 import { DetailView } from "./detail";
 
 const SKELETON_COUNT = 4;

package/templates/ecom/vite.config.ts

@@ -1,6 +1,6 @@
+import { skybridge } from "@skybridge/vite-plugin";
 import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";
 import react from "@vitejs/plugin-react";
-import { skybridge } from "skybridge/vite";
 import { defineConfig, type PluginOption } from "vite";
 
 export default defineConfig({