create-skybridge 0.0.0-dev.356dbec → 0.0.0-dev.35a7b38

package/templates/ecom/src/design/sprinkles.css.ts

@@ -0,0 +1,128 @@
+import { createSprinkles, defineProperties } from "@vanilla-extract/sprinkles";
+import { colors } from "./contract.css";
+import { primitives } from "./primitives.css";
+
+/**
+ * Atomic style props built on the primitives + color contract. Use sprinkles
+ * for one-off layout/spacing/color on an element, e.g.
+ *   sprinkles({ display: "flex", gap: "s", color: "intense" })
+ *
+ * Structural component styling belongs in a co-located `.css.ts` `style()`
+ * block; sprinkles is the thin glue layer on top.
+ */
+
+const spaceProperties = defineProperties({
+  properties: {
+    padding: primitives.space,
+    paddingTop: primitives.space,
+    paddingRight: primitives.space,
+    paddingBottom: primitives.space,
+    paddingLeft: primitives.space,
+    margin: primitives.space,
+    marginTop: primitives.space,
+    marginRight: primitives.space,
+    marginBottom: primitives.space,
+    marginLeft: primitives.space,
+    gap: primitives.space,
+    rowGap: primitives.space,
+    columnGap: primitives.space,
+  },
+  shorthands: {
+    p: ["padding"],
+    pt: ["paddingTop"],
+    pr: ["paddingRight"],
+    pb: ["paddingBottom"],
+    pl: ["paddingLeft"],
+    px: ["paddingLeft", "paddingRight"],
+    py: ["paddingTop", "paddingBottom"],
+    m: ["margin"],
+    mt: ["marginTop"],
+    mr: ["marginRight"],
+    mb: ["marginBottom"],
+    ml: ["marginLeft"],
+    mx: ["marginLeft", "marginRight"],
+    my: ["marginTop", "marginBottom"],
+  },
+});
+
+const colorProperties = defineProperties({
+  properties: {
+    backgroundColor: {
+      ...colors.surface,
+      accent: colors.common.accent,
+      invertAccent: colors.common.invertAccent,
+      highlight: colors.common.highlight,
+      transparent: "transparent",
+    },
+    color: {
+      ...colors.content,
+      accent: colors.common.accent,
+      invertAccent: colors.common.invertAccent,
+      highlight: colors.common.highlight,
+      error: colors.common.error,
+      success: colors.common.success,
+    },
+    borderColor: {
+      ...colors.border,
+      accent: colors.common.accent,
+      invertAccent: colors.common.invertAccent,
+      highlight: colors.common.highlight,
+      transparent: "transparent",
+    },
+  },
+});
+
+const radiusProperties = defineProperties({
+  properties: {
+    borderRadius: primitives.radius,
+    borderTopLeftRadius: primitives.radius,
+    borderTopRightRadius: primitives.radius,
+    borderBottomLeftRadius: primitives.radius,
+    borderBottomRightRadius: primitives.radius,
+  },
+});
+
+const typographyProperties = defineProperties({
+  properties: {
+    fontFamily: primitives.font.family,
+    fontWeight: primitives.font.weight,
+    fontSize: primitives.font.size,
+    lineHeight: primitives.font.lineHeight,
+    letterSpacing: primitives.font.letterSpacing,
+  },
+});
+
+const strokeProperties = defineProperties({
+  properties: {
+    borderWidth: primitives.stroke,
+  },
+});
+
+const layoutProperties = defineProperties({
+  properties: {
+    display: ["none", "flex", "inline-flex", "block", "inline-block", "grid"],
+    flexDirection: ["row", "column", "row-reverse", "column-reverse"],
+    alignItems: ["flex-start", "center", "flex-end", "stretch", "baseline"],
+    justifyContent: [
+      "flex-start",
+      "center",
+      "flex-end",
+      "space-between",
+      "space-around",
+      "space-evenly",
+    ],
+    flexWrap: ["wrap", "nowrap", "wrap-reverse"],
+    textAlign: ["left", "center", "right"],
+  },
+});
+
+export const sprinkles = createSprinkles(
+  spaceProperties,
+  colorProperties,
+  radiusProperties,
+  typographyProperties,
+  strokeProperties,
+  layoutProperties,
+);
+
+export type Sprinkles = Parameters<typeof sprinkles>[0];

package/templates/ecom/src/design/themes/dark.css.ts

@@ -0,0 +1,36 @@
+import { createTheme } from "@vanilla-extract/css";
+import { colors } from "../contract.css";
+import { primitives } from "../primitives.css";
+
+/**
+ * Dark palette. Fills the same contract slots as light.css.ts (surface and
+ * content swap ends of the grey ramp).
+ *
+ * @todo: tune these mappings to your brand.
+ */
+export const darkTheme = createTheme(colors, {
+  surface: {
+    extraLight: primitives.grey.black,
+    light: primitives.grey["900"],
+    subtle: primitives.grey["700"],
+    intense: primitives.grey["400"],
+  },
+  content: {
+    intense: primitives.grey["50"],
+    subtle: primitives.grey["300"],
+    invertIntense: primitives.grey["900"],
+    invertSubtle: primitives.grey["500"],
+  },
+  border: {
+    thin: primitives.grey["700"],
+    subtle: primitives.grey["600"],
+    intense: primitives.grey["400"],
+  },
+  common: {
+    accent: primitives.accent["400"],
+    invertAccent: primitives.grey.black,
+    highlight: primitives.accent["400"],
+    error: primitives.status.error,
+    success: primitives.status.success,
+  },
+});

package/templates/ecom/src/design/themes/light.css.ts

@@ -0,0 +1,36 @@
+import { createTheme } from "@vanilla-extract/css";
+import { colors } from "../contract.css";
+import { primitives } from "../primitives.css";
+
+/**
+ * Light palette: maps each semantic slot to a primitive.
+ *
+ * @todo: tune these mappings to your brand. dark.css.ts must fill the same
+ * slots (the contract enforces it).
+ */
+export const lightTheme = createTheme(colors, {
+  surface: {
+    extraLight: primitives.grey.white,
+    light: primitives.grey["50"],
+    subtle: primitives.grey["200"],
+    intense: primitives.grey["400"],
+  },
+  content: {
+    intense: primitives.grey["900"],
+    subtle: primitives.grey["500"],
+    invertIntense: primitives.grey["50"],
+    invertSubtle: primitives.grey["300"],
+  },
+  border: {
+    thin: primitives.grey["200"],
+    subtle: primitives.grey["300"],
+    intense: primitives.grey["400"],
+  },
+  common: {
+    accent: primitives.accent["600"],
+    invertAccent: primitives.grey.white,
+    highlight: primitives.accent["600"],
+    error: primitives.status.error,
+    success: primitives.status.success,
+  },
+});

package/templates/ecom/src/design/tokens.ts

@@ -0,0 +1,8 @@
+// Barrel for the design system. Import tokens from here rather than reaching
+// into individual files.
+export { colors } from "./contract.css";
+export { primitives } from "./primitives.css";
+export { text } from "./recipes/typography.css";
+export { type Sprinkles, sprinkles } from "./sprinkles.css";
+export { darkTheme } from "./themes/dark.css";
+export { lightTheme } from "./themes/light.css";

package/templates/ecom/src/helpers.ts

@@ -0,0 +1,4 @@
+import { generateHelpers } from "skybridge/web";
+import type { AppType } from "./server.js";
+
+export const { useToolInfo, useCallTool } = generateHelpers<AppType>();

package/templates/ecom/src/i18n.ts

@@ -0,0 +1,34 @@
+import { useUser } from "skybridge/web";
+
+// Centralized UI labels. The active locale comes from the host via useUser();
+// useLabels matches on the language subtag ("en-US" -> "en") and falls back to
+// English for anything unlisted.
+// @todo: adapt the English copy to your brand voice, and add a locale key (e.g.
+// `fr`) with the same shape for each language you want to support.
+const LABELS = {
+  en: {
+    outOfStock: "Out of stock",
+    noProducts: "No products to show.",
+    carousel: "carousel",
+    products: "Products",
+    previous: "Previous",
+    next: "Next",
+    // Detail view.
+    viewOnSite: "View on site",
+    selectOptions: "Select options",
+    priceOnRequest: "Price on request",
+    specifications: "Specifications",
+    readMore: "Read more",
+    readLess: "Read less",
+  },
+} as const;
+
+const DEFAULT_LOCALE = "en";
+
+export type Labels = (typeof LABELS)[typeof DEFAULT_LOCALE];
+
+export function useLabels(): Labels {
+  const { locale } = useUser();
+  const lang = locale.split("-")[0] ?? DEFAULT_LOCALE;
+  return lang in LABELS ? LABELS[lang as keyof typeof LABELS] : LABELS.en;
+}

package/templates/ecom/src/index.css

@@ -0,0 +1,9 @@
+@import "./design/fonts.css";
+
+/* The view mounts in a host iframe whose <body> keeps the user-agent default
+   margin (~8px). Zero it out so the surface paints edge to edge. */
+html,
+body {
+  margin: 0;
+  padding: 0;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Zero-dep class-name joiner. vanilla-extract's `recipe`/`style` return plain
+ * strings, so merging a recipe class with an optional consumer `className`
+ * just needs string concatenation that tolerates `undefined`/`false`/`null`.
+ *
+ *   className={cx(text({ style: "bodyM" }), sprinkles({ color: "accent" }))}
+ */
+export const cx = (...classes: (string | false | null | undefined)[]) =>
+  classes.filter(Boolean).join(" ");

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

@@ -0,0 +1,9 @@
+import type { Price } from "../types.js";
+
+// Pass useUser().locale from the view; omit for the runtime default.
+export function formatPrice(price: Price, locale?: string): string {
+  return new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency: price.currency,
+  }).format(price.amount);
+}

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

@@ -0,0 +1,79 @@
+import type { Product, Variant } from "../tools/render-carousel.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.
+
+// 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.
+ */
+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],
+    ),
+  );
+}
+
+/**
+ * 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").
+ */
+export function selectableValues(
+  product: Product,
+  axisId: string,
+  selection: Selection,
+): Set<string> {
+  const reachable = new Set<string>();
+  for (const variant of product.variants) {
+    let matchesOthers = true;
+    for (const option of product.options) {
+      if (option.id === axisId) {
+        continue;
+      }
+      const chosen = selection[option.id];
+      if (chosen != null && variant.selection[option.id] !== chosen) {
+        matchesOthers = false;
+        break;
+      }
+    }
+    if (matchesOthers) {
+      reachable.add(variant.selection[axisId]);
+    }
+  }
+  return reachable;
+}
+
+/**
+ * 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.
+ */
+export function initialSelection(product: Product): Selection {
+  let base: Variant | undefined;
+  for (const variant of product.variants) {
+    if (variant.id === product.id) {
+      base = variant;
+      break;
+    }
+  }
+  base ??= product.variants[0];
+  return base ? { ...base.selection } : {};
+}

package/templates/ecom/src/server.ts

@@ -0,0 +1,43 @@
+import { existsSync } from "node:fs";
+import { McpServer } from "skybridge/server";
+import { CAROUSEL_RANGE, MIN_SEARCH_ITERATIONS } from "./config.js";
+import {
+  renderCarouselDefinition,
+  renderCarouselHandler,
+} from "./tools/render-carousel.js";
+import {
+  searchProductsDefinition,
+  searchProductsHandler,
+} from "./tools/search-products.js";
+
+// Load .env into process.env when present (native to Node, no dependency).
+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: `\
+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. \
+Stay silent while searching: emit NO text between calls. Speak only \
+once the carousel renders. Never call a category unavailable before searching.
+
+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);
+
+export default await server.run();
+
+export type AppType = typeof server;

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

@@ -0,0 +1,242 @@
+import { z } from "zod";
+import { CAROUSEL_MAX_SIZE, CAROUSEL_RANGE } from "../config.js";
+import {
+  type Attribute,
+  AttributeSchema,
+  type Price,
+  PriceSchema,
+} 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;
+};
+
+// ---------------------------------------------------------------------------
+// Input
+// ---------------------------------------------------------------------------
+
+const inputSchema = {
+  ids: z
+    .array(z.string())
+    .min(1)
+    .max(CAROUSEL_MAX_SIZE)
+    .describe("Product IDs to present, in display order."),
+};
+
+type RenderInput = z.infer<z.ZodObject<typeof inputSchema>>;
+
+// ---------------------------------------------------------------------------
+// Output — model-facing grounding, for the LLM ONLY. The carousel view is NOT
+// built from this; it renders from the full data in `_meta`. Keep it to what the
+// model needs to reference and compare the displayed products afterward.
+// ---------------------------------------------------------------------------
+
+const outputSchema = {
+  products: z
+    .array(
+      z.object({
+        id: z.string().describe("Product SKU or reference."),
+        title: z.string(),
+        options: z
+          .array(z.object({ label: z.string(), values: z.array(z.string()) }))
+          .describe("Variations available (e.g. colors, sizes)."),
+        description: z.string().optional(),
+        price: PriceSchema.optional(),
+        outOfStock: z.boolean(),
+        attributes: z
+          .array(AttributeSchema)
+          .describe("Product facts (specs, promo labels…)."),
+      }),
+    )
+    .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.",
+    ),
+};
+
+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
+// full data stays in `_meta` for the view.
+// @todo: choose what the model sees per product. Grounding only: no
+// presentational data (media, styling); that rides in `_meta` for the view.
+// ---------------------------------------------------------------------------
+
+function toStructuredContent(products: Product[]): RenderOutput {
+  const groundingProducts: RenderOutput["products"] = [];
+
+  for (const product of products) {
+    const { card } = product;
+
+    const options: { label: string; values: string[] }[] = [];
+    for (const option of product.options) {
+      const values: string[] = [];
+      for (const value of option.values) {
+        values.push(value.label);
+      }
+      options.push({ label: option.label, values });
+    }
+
+    groundingProducts.push({
+      id: product.id,
+      title: card.title,
+      description: card.description,
+      price: card.price,
+      outOfStock: card.outOfStock ?? false,
+      options,
+      attributes: card.attributes,
+    });
+  }
+
+  return { products: groundingProducts };
+}
+
+// ---------------------------------------------------------------------------
+// Tool (registered from server.ts to keep the typed tool chain intact)
+// ---------------------------------------------------------------------------
+
+export const renderCarouselDefinition = {
+  name: "render-carousel" as const,
+
+  // @todo: adapt the wording to your catalog and brand voice (tone, vocabulary,
+  // how to present products). The behavioral rules below apply to any catalog.
+  description: `\
+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.
+
+## 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).
+
+## After the carousel
+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.`,
+  annotations: {
+    readOnlyHint: true,
+    openWorldHint: false,
+    destructiveHint: false,
+  },
+
+  // @todo: customize the status messages shown in ChatGPT while the tool runs.
+  _meta: {
+    "openai/toolInvocation/invoking": "Loading product carousel",
+    "openai/toolInvocation/invoked": "Loaded product carousel",
+  },
+
+  // The carousel and product details UI rendered inline in the conversation.
+  view: {
+    // `as const` keeps this a literal (like `name` above) so it matches the
+    // generated ViewNameRegistry; a bare string widens and fails the build.
+    component: "carousel" as const,
+    description: "Browse the curated products.",
+    // @todo: declare the CSP domains this view needs. Add your image origins to
+    // `resourceDomains` so product images load, and the product site to
+    // `redirectDomains` so the detail view's "View on site" link and the host's
+    // "Open in app" URL (useOpenExternal / setOpenInAppUrl) are allowed.
+    // csp: {
+    //   resourceDomains: ["https://images.example.com"],
+    //   redirectDomains: ["https://www.example.com"],
+    // },
+  },
+
+  inputSchema,
+  outputSchema,
+};
+
+export async function renderCarouselHandler({ ids }: RenderInput) {
+  const products = await getProducts(ids);
+
+  return {
+    // Full products (incl. variants) for the view; not in model context.
+    _meta: { products },
+    structuredContent: toStructuredContent(products),
+    content: [
+      {
+        type: "text" as const,
+        text: `Rendered ${products.length} product(s) in the carousel.`,
+      },
+    ],
+    isError: false,
+  };
+}