create-skybridge 0.0.0-dev.0f97936 → 0.0.0-dev.0fa5252

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,35 @@
+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",
+    combinationUnavailable: "Combination unavailable",
+    noProducts: "No products to show.",
+    carousel: "carousel",
+    products: "Products",
+    previous: "Previous",
+    next: "Next",
+    // Detail view.
+    reference: "Ref.",
+    viewOnSite: "View on site",
+    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,150 @@
+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. 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 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 {
+  return product.variants.find((variant) =>
+    product.options.every(
+      (option) =>
+        (variant.selection[option.id] ?? null) ===
+        (selection[option.id] ?? null),
+    ),
+  );
+}
+
+/**
+ * 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 axisStates(
+  product: Product,
+  axisId: string,
+  selection: Selection,
+): Map<string, "inStock" | "soldOut"> {
+  const states = new Map<string, "inStock" | "soldOut">();
+  for (const variant of product.variants) {
+    let matchesEarlier = true;
+    for (const option of product.options) {
+      if (option.id === axisId) {
+        break; // only the axes above constrain this one
+      }
+      const chosen = selection[option.id];
+      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 (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 next;
+}
+
+/**
+ * The selection to preselect when a product opens: the variant the client
+ * 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 ??= firstInStock ?? 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 keywords or page deeper. \
+Stay silent while searching: emit NO text between calls. Speak only \
+once the carousel renders.
+
+RENDER: After curating, call render-carousel with the chosen product IDs (aim for ${CAROUSEL_RANGE}). \
+Speak once it renders, then recommend products 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,161 @@
+import { z } from "zod";
+import { getProducts } from "../catalog/index.js";
+import { CAROUSEL_MAX_SIZE, CAROUSEL_RANGE } from "../config.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. Data access lives in
+// `src/catalog/`; everything else this tool needs lives in this file.
+
+// ---------------------------------------------------------------------------
+// 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(),
+        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 facts.",
+    ),
+};
+
+type RenderOutput = z.infer<z.ZodObject<typeof outputSchema>>;
+
+// ---------------------------------------------------------------------------
+// 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,
+      specs: card.specs,
+    });
+  }
+
+  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. 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).
+
+## 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 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,
+    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,
+  };
+}