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

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

@@ -0,0 +1,101 @@
+import { createGlobalTheme } from "@vanilla-extract/css";
+
+/**
+ * Non-mode-aware design primitives: the raw scales every theme and recipe
+ * draws from. Values here are brand-neutral placeholders.
+ *
+ * @todo: replace these with your brand's real tokens (ideally extracted from
+ * a Figma design file). Change values, not the shape: the space/radius/font
+ * keys are referenced by sprinkles.css.ts and the recipes. Nothing outside
+ * this file should hard-code a hex, size, or spacing value.
+ */
+export const primitives = createGlobalTheme(":root", {
+  // Spacing scale (4px based). Used for padding, margin, and gap via sprinkles.
+  space: {
+    none: "0",
+    "5xs": "2px",
+    "4xs": "4px",
+    "3xs": "8px",
+    "2xs": "12px",
+    xs: "16px",
+    s: "24px",
+    m: "32px",
+    l: "40px",
+    xl: "48px",
+    "2xl": "56px",
+    "3xl": "64px",
+  },
+  radius: {
+    none: "0",
+    xs: "2px",
+    s: "4px",
+    m: "8px",
+    l: "16px",
+    xl: "32px",
+    full: "999px",
+  },
+  font: {
+    family: {
+      // @todo: swap in your brand font (add its @font-face to fonts.css). The
+      // system stack is the zero-asset default.
+      primary:
+        '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+    },
+    weight: {
+      regular: "400",
+      medium: "500",
+      semibold: "600",
+      bold: "700",
+    },
+    size: {
+      xs: "12px",
+      s: "14px",
+      m: "16px",
+      l: "20px",
+      xl: "24px",
+      "2xl": "32px",
+      "3xl": "40px",
+    },
+    lineHeight: {
+      tight: "1.25",
+      normal: "1.5",
+    },
+    letterSpacing: {
+      default: "0",
+      wide: "0.5px",
+    },
+  },
+  stroke: {
+    thin: "1px",
+    medium: "1.5px",
+    thick: "2px",
+  },
+  // Raw greyscale ramp. Themes pick from these for surface/content/border.
+  grey: {
+    white: "#ffffff",
+    "50": "#f8f8f8",
+    "100": "#f2f2f2",
+    "200": "#e1e1e1",
+    "300": "#b4b4b4",
+    "400": "#929292",
+    "500": "#727272",
+    "600": "#636363",
+    "700": "#4c4c4c",
+    "800": "#333333",
+    "900": "#1a1a1a",
+    black: "#000000",
+  },
+  // @todo: your brand accent ramp (call-to-action, links, highlights). Steps
+  // named by lightness, like the grey ramp; each theme picks the shade that
+  // reads well on its surface (light mode the darker step, dark mode the
+  // lighter one). Add more steps as needed.
+  accent: {
+    "400": "#7ba0f5",
+    "600": "#3b6cf0",
+  },
+  // Status colors, shared across themes.
+  status: {
+    error: "#c53929",
+    success: "#5c7d0b",
+  },
+});

package/templates/ecom/src/design/recipes/typography.css.ts

@@ -0,0 +1,75 @@
+import { recipe } from "@vanilla-extract/recipes";
+import { primitives } from "../primitives.css";
+
+/**
+ * The one text style, driven by variants. Call it as:
+ *   text({ style: "headingM", weight: "medium" })
+ *
+ * `style` picks the size/line-height pair; `weight` picks the font weight.
+ * This is the workhorse recipe: use it for all typography rather than setting
+ * fontSize/fontWeight by hand.
+ *
+ * @todo: adjust the styles to your type scale. Add a component recipe (button,
+ * tag, card) only when a component has real variants; otherwise style with
+ * sprinkles or a `style()` block.
+ */
+export const text = recipe({
+  base: {
+    fontFamily: primitives.font.family.primary,
+    letterSpacing: primitives.font.letterSpacing.default,
+    fontWeight: primitives.font.weight.regular,
+    margin: 0,
+  },
+  variants: {
+    style: {
+      display: {
+        fontSize: primitives.font.size["3xl"],
+        lineHeight: primitives.font.lineHeight.tight,
+      },
+      headingL: {
+        fontSize: primitives.font.size["2xl"],
+        lineHeight: primitives.font.lineHeight.tight,
+      },
+      headingM: {
+        fontSize: primitives.font.size.xl,
+        lineHeight: primitives.font.lineHeight.tight,
+      },
+      headingS: {
+        fontSize: primitives.font.size.l,
+        lineHeight: primitives.font.lineHeight.tight,
+      },
+      bodyM: {
+        fontSize: primitives.font.size.m,
+        lineHeight: primitives.font.lineHeight.normal,
+      },
+      bodyS: {
+        fontSize: primitives.font.size.s,
+        lineHeight: primitives.font.lineHeight.normal,
+      },
+      labelM: {
+        fontSize: primitives.font.size.m,
+        lineHeight: primitives.font.lineHeight.tight,
+      },
+      labelS: {
+        fontSize: primitives.font.size.s,
+        lineHeight: primitives.font.lineHeight.tight,
+      },
+      overline: {
+        fontSize: primitives.font.size.xs,
+        lineHeight: primitives.font.lineHeight.normal,
+        letterSpacing: primitives.font.letterSpacing.wide,
+        textTransform: "uppercase",
+      },
+    },
+    weight: {
+      regular: { fontWeight: primitives.font.weight.regular },
+      medium: { fontWeight: primitives.font.weight.medium },
+      semibold: { fontWeight: primitives.font.weight.semibold },
+      bold: { fontWeight: primitives.font.weight.bold },
+    },
+  },
+  defaultVariants: {
+    style: "bodyM",
+    weight: "regular",
+  },
+});

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;