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

package/templates/demo/vite.config.ts

@@ -1,11 +1,11 @@
 import path from "node:path";
+import { skybridge } from "@skybridge/vite-plugin";
 import tailwindcss from "@tailwindcss/vite";
 import react from "@vitejs/plugin-react";
-import { skybridge } from "skybridge/vite";
 import { defineConfig } from "vite";
 
 export default defineConfig({
-  plugins: [skybridge(), react(), tailwindcss()],
+  plugins: [skybridge({ evals: {} }), react(), tailwindcss()],
   server: {
     forwardConsole: {
       unhandledErrors: true,
@@ -14,7 +14,7 @@ export default defineConfig({
   },
   resolve: {
     alias: {
-      "@": path.resolve(__dirname, "./src"),
+      "@": path.resolve(import.meta.dirname, "./src"),
     },
   },
 });

package/templates/ecom/.env.template

@@ -1,2 +1,7 @@
 # Copy to .env and fill in. Sourced by the server at startup.
 API_KEY=
+
+# Only for the Shopify catalog provider (src/catalog/shopify.ts).
+# The token is the public Storefront API access token, not an Admin key.
+SHOPIFY_STORE_DOMAIN=
+SHOPIFY_STOREFRONT_TOKEN=

package/templates/ecom/README.md

@@ -48,7 +48,8 @@ This command starts:
 
 ```
 ├── src/
-│   ├── server.ts         # Server entry point
+│   ├── index.ts          # Entry point (starts the app)
+│   ├── server.ts         # App definition (tools, views)
 │   └── helpers.ts        # Shared utilities
 ├── vite.config.ts
 ├── alpic.json            # Deployment config

package/templates/ecom/node_modules/.bin/alpic

@@ -10,9 +10,9 @@ case `uname` in
 esac
 
 if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.156.0_@opentelemetry+api@1.9.1_@opentelemetry+core@2.9.0_@opentelemetry+api@1.9_1e4d6b8f8010991ae8bdea8fb1777fd0/node_modules/alpic/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.156.0_@opentelemetry+api@1.9.1_@opentelemetry+core@2.9.0_@opentelemetry+api@1.9_1e4d6b8f8010991ae8bdea8fb1777fd0/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.157.0_@opentelemetry+api@1.9.1_@opentelemetry+core@2.9.0_@opentelemetry+api@1.9_8f13b9696a5fc8688953a3b2ccd28385/node_modules/alpic/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.157.0_@opentelemetry+api@1.9.1_@opentelemetry+core@2.9.0_@opentelemetry+api@1.9_8f13b9696a5fc8688953a3b2ccd28385/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
 else
-  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.156.0_@opentelemetry+api@1.9.1_@opentelemetry+core@2.9.0_@opentelemetry+api@1.9_1e4d6b8f8010991ae8bdea8fb1777fd0/node_modules/alpic/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.156.0_@opentelemetry+api@1.9.1_@opentelemetry+core@2.9.0_@opentelemetry+api@1.9_1e4d6b8f8010991ae8bdea8fb1777fd0/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.157.0_@opentelemetry+api@1.9.1_@opentelemetry+core@2.9.0_@opentelemetry+api@1.9_8f13b9696a5fc8688953a3b2ccd28385/node_modules/alpic/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.157.0_@opentelemetry+api@1.9.1_@opentelemetry+core@2.9.0_@opentelemetry+api@1.9_8f13b9696a5fc8688953a3b2ccd28385/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
 fi
 if [ -x "$basedir/node" ]; then
   exec "$basedir/node"  "$basedir/../alpic/bin/run.js" "$@"

package/templates/ecom/node_modules/.bin/ladle

@@ -10,9 +10,9 @@ case `uname` in
 esac
 
 if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/@ladle+react@5.1.1_@types+node@24.13.2_@types+react@19.2.17_jiti@2.7.0_lightningcss@1.3_1166394f95df9cef33a0930b8ede5a5f/node_modules/@ladle/react/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/@ladle+react@5.1.1_@types+node@24.13.2_@types+react@19.2.17_jiti@2.7.0_lightningcss@1.3_1166394f95df9cef33a0930b8ede5a5f/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/@ladle+react@5.1.1_@swc+helpers@0.5.23_@types+node@24.13.3_@types+react@19.2.17_jiti@2._9105ecfa2ac4b29fe87a036530c3844f/node_modules/@ladle/react/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/@ladle+react@5.1.1_@swc+helpers@0.5.23_@types+node@24.13.3_@types+react@19.2.17_jiti@2._9105ecfa2ac4b29fe87a036530c3844f/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
 else
-  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/@ladle+react@5.1.1_@types+node@24.13.2_@types+react@19.2.17_jiti@2.7.0_lightningcss@1.3_1166394f95df9cef33a0930b8ede5a5f/node_modules/@ladle/react/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/@ladle+react@5.1.1_@types+node@24.13.2_@types+react@19.2.17_jiti@2.7.0_lightningcss@1.3_1166394f95df9cef33a0930b8ede5a5f/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/@ladle+react@5.1.1_@swc+helpers@0.5.23_@types+node@24.13.3_@types+react@19.2.17_jiti@2._9105ecfa2ac4b29fe87a036530c3844f/node_modules/@ladle/react/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/@ladle+react@5.1.1_@swc+helpers@0.5.23_@types+node@24.13.3_@types+react@19.2.17_jiti@2._9105ecfa2ac4b29fe87a036530c3844f/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
 fi
 if [ -x "$basedir/node" ]; then
   exec "$basedir/node"  "$basedir/../@ladle/react/lib/cli/cli.js" "$@"

package/templates/ecom/node_modules/.bin/vite

@@ -10,9 +10,9 @@ case `uname` in
 esac
 
 if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/vite@8.1.5_@types+node@24.13.2_esbuild@0.28.1_jiti@2.7.0_terser@5.44.1_tsx@4.23.0_yaml@2.9.0/node_modules/vite/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/vite@8.1.5_@types+node@24.13.2_esbuild@0.28.1_jiti@2.7.0_terser@5.44.1_tsx@4.23.0_yaml@2.9.0/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/vite@8.1.5_@types+node@24.13.3_esbuild@0.28.1_jiti@2.7.0_terser@5.44.1_tsx@4.23.0_yaml@2.9.0/node_modules/vite/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/vite@8.1.5_@types+node@24.13.3_esbuild@0.28.1_jiti@2.7.0_terser@5.44.1_tsx@4.23.0_yaml@2.9.0/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
 else
-  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/vite@8.1.5_@types+node@24.13.2_esbuild@0.28.1_jiti@2.7.0_terser@5.44.1_tsx@4.23.0_yaml@2.9.0/node_modules/vite/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/vite@8.1.5_@types+node@24.13.2_esbuild@0.28.1_jiti@2.7.0_terser@5.44.1_tsx@4.23.0_yaml@2.9.0/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/vite@8.1.5_@types+node@24.13.3_esbuild@0.28.1_jiti@2.7.0_terser@5.44.1_tsx@4.23.0_yaml@2.9.0/node_modules/vite/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/vite@8.1.5_@types+node@24.13.3_esbuild@0.28.1_jiti@2.7.0_terser@5.44.1_tsx@4.23.0_yaml@2.9.0/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
 fi
 if [ -x "$basedir/node" ]; then
   exec "$basedir/node"  "$basedir/../vite/bin/vite.js" "$@"

package/templates/ecom/package.json

@@ -16,13 +16,14 @@
   "dependencies": {
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "skybridge": "^0.0.0-dev.994f77c",
+    "skybridge": "^0.0.0-dev.995023d",
     "vite": "^8.1.3",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@ladle/react": "^5.1.1",
-    "@skybridge/devtools": "^1.2.4",
+    "@skybridge/devtools": "^0.0.0-dev.995023d",
+    "@skybridge/vite-plugin": "^0.0.0-dev.995023d",
     "@types/node": "^24.13.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",

package/templates/ecom/src/catalog/index.ts

@@ -0,0 +1,19 @@
+// The catalog: the app's single data seam. Both tools read products through
+// these two functions, and nothing else in the app touches a backend.
+//
+// @todo: pick your provider. Ship one of the modules next to this file, or add
+// your own (same two exports, same types) and re-export it here:
+//   ./mock.js      placeholder catalog, no backend needed (default)
+//   ./shopify.js   Shopify Storefront API, set the SHOPIFY_* vars in .env
+//
+// Writing your own: `search(input)` returns a `SearchResult`, `getProducts(ids)`
+// resolves ids in the requested order (that is the display order, so resolve by
+// id, never by catalog order). Both map your backend's rows into `Product`s, and
+// how you group them depends on your catalog:
+//   - simple products: one `Product` with a single variant, `options: []`
+//   - grouped: one `Product` per product, `card` = union of its variants
+//   - one card per variant: `card` = that variant
+// Either way `variants` holds 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 `Product`: order is semantic).
+export { getProducts, search } from "./mock.js";

package/templates/ecom/src/catalog/mock.ts

@@ -0,0 +1,134 @@
+import type { SearchInput } from "../tools/search-products.js";
+import type { Product, SearchResult, Spec } from "../types.js";
+
+// Placeholder catalog provider, so both tools answer before a backend exists.
+// Images are inline SVG placeholders, so no CSP domain is needed.
+// @todo: delete this module once you point `./index.js` at a real provider.
+
+function shot(fill: string): 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%3C/svg%3E`;
+}
+
+const JACKET_SPECS: Spec[] = [
+  { label: "Material", value: "Water-repellent cotton" },
+  { label: "Fit", value: "Relaxed" },
+];
+
+// Deliberately long, to exercise the detail page's scroll and "read more".
+const JACKET_DESCRIPTION = "Relaxed-fit jacket in water-repellent cotton.";
+
+const MOCK_PRODUCTS: Product[] = [
+  {
+    id: "field-jacket",
+    options: [
+      {
+        id: "color",
+        label: "Color",
+        values: [
+          { id: "black", label: "Black", media: shot("2b2b2b") },
+          { id: "sand", label: "Sand", media: shot("d8c7a8") },
+        ],
+      },
+    ],
+    variants: [
+      {
+        id: "fj-black",
+        selection: { color: "black" },
+        title: "Field jacket — Black",
+        description: JACKET_DESCRIPTION,
+        price: { amount: 229, currency: "EUR" },
+        media: [shot("2b2b2b")],
+        url: "https://example.com/field-jacket-black",
+        specs: JACKET_SPECS,
+      },
+      {
+        id: "fj-sand",
+        selection: { color: "sand" },
+        title: "Field jacket — Sand",
+        description: JACKET_DESCRIPTION,
+        price: { amount: 249, currency: "EUR" },
+        media: [shot("d8c7a8")],
+        url: "https://example.com/field-jacket-sand",
+        specs: JACKET_SPECS,
+      },
+    ],
+    card: {
+      title: "Field jacket",
+      description: "Relaxed-fit jacket in water-repellent cotton.",
+      price: { amount: 229, currency: "EUR" },
+      media: [shot("2b2b2b")],
+      specs: JACKET_SPECS,
+    },
+  },
+  {
+    id: "canvas-tote",
+    options: [],
+    variants: [
+      {
+        id: "canvas-tote",
+        selection: {},
+        title: "Canvas tote",
+        description: "Sturdy everyday tote with an inner pocket.",
+        price: { amount: 39, currency: "EUR" },
+        media: [shot("e1e1e1")],
+        url: "https://example.com/canvas-tote",
+        specs: [{ label: "Material", value: "Cotton canvas" }],
+      },
+    ],
+    card: {
+      title: "Canvas tote",
+      description: "Sturdy everyday tote with an inner pocket.",
+      price: { amount: 39, currency: "EUR" },
+      media: [shot("e1e1e1")],
+      specs: [{ label: "Material", value: "Cotton canvas" }],
+    },
+  },
+  {
+    id: "wool-beanie",
+    options: [],
+    variants: [
+      {
+        id: "wool-beanie",
+        selection: {},
+        title: "Wool beanie",
+        description: "Ribbed merino beanie with a folded brim.",
+        price: { amount: 45, currency: "EUR" },
+        media: [shot("6b7f9e")],
+        url: "https://example.com/wool-beanie",
+        outOfStock: true,
+        specs: [{ label: "Material", value: "Merino wool" }],
+      },
+    ],
+    card: {
+      title: "Wool beanie",
+      description: "Ribbed merino beanie with a folded brim.",
+      price: { amount: 45, currency: "EUR" },
+      media: [shot("6b7f9e")],
+      outOfStock: true,
+      specs: [{ label: "Material", value: "Merino wool" }],
+    },
+  },
+];
+
+// Ignores the input: every mock product matches every query.
+export async function search(_input: SearchInput): Promise<SearchResult> {
+  return {
+    products: MOCK_PRODUCTS,
+    pages: { current: 1, total: 1 },
+    totalHits: MOCK_PRODUCTS.length,
+  };
+}
+
+// Requested order is the display order, so resolve by id, not catalog order.
+export async function getProducts(ids: string[]): Promise<Product[]> {
+  const products: Product[] = [];
+  for (const id of ids) {
+    for (const product of MOCK_PRODUCTS) {
+      if (product.id === id) {
+        products.push(product);
+        break;
+      }
+    }
+  }
+  return products;
+}

package/templates/ecom/src/catalog/shopify.ts

@@ -0,0 +1,264 @@
+import type { SearchInput } from "../tools/search-products.js";
+import type {
+  Option,
+  Price,
+  Product,
+  SearchResult,
+  Spec,
+  Variant,
+} from "../types.js";
+
+// Shopify Storefront API provider. To use it:
+//   1. re-export this module from `./index.js` instead of `./mock.js`
+//   2. set SHOPIFY_STORE_DOMAIN and SHOPIFY_STOREFRONT_TOKEN in .env
+//   3. uncomment the `csp` block in `src/tools/render-carousel.ts` with
+//      `https://cdn.shopify.com` and your store domain
+//
+// Product ids are Shopify handles, not GIDs: stable, readable, and far cheaper
+// in model context than `gid://shopify/Product/8123456789`.
+
+const API_VERSION = "2026-07";
+const PAGE_SIZE = 20;
+
+// Only the fields this app renders. Options are derived from the variants'
+// `selectedOptions`, so the product-level `options` field is not queried.
+const PRODUCT_FIELDS = `
+fragment ProductFields on Product {
+  handle
+  title
+  description
+  vendor
+  productType
+  onlineStoreUrl
+  availableForSale
+  priceRange { minVariantPrice { amount currencyCode } }
+  images(first: 10) { nodes { url } }
+  variants(first: 100) {
+    nodes {
+      id
+      title
+      availableForSale
+      price { amount currencyCode }
+      image { url }
+      selectedOptions { name value }
+    }
+  }
+}`;
+
+type ShopifyMoney = { amount: string; currencyCode: string };
+
+type ShopifyProduct = {
+  handle: string;
+  title: string;
+  description: string;
+  vendor: string;
+  productType: string;
+  onlineStoreUrl: string | null;
+  availableForSale: boolean;
+  priceRange: { minVariantPrice: ShopifyMoney };
+  images: { nodes: { url: string }[] };
+  variants: {
+    nodes: {
+      id: string;
+      title: string;
+      availableForSale: boolean;
+      price: ShopifyMoney;
+      image: { url: string } | null;
+      selectedOptions: { name: string; value: string }[];
+    }[];
+  };
+};
+
+async function storefront(query: string, variables: Record<string, unknown>) {
+  const domain = process.env.SHOPIFY_STORE_DOMAIN;
+  const token = process.env.SHOPIFY_STOREFRONT_TOKEN;
+  if (!domain || !token) {
+    throw new Error(
+      "Missing SHOPIFY_STORE_DOMAIN or SHOPIFY_STOREFRONT_TOKEN in the environment.",
+    );
+  }
+
+  const response = await fetch(
+    `https://${domain}/api/${API_VERSION}/graphql.json`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Shopify-Storefront-Access-Token": token,
+      },
+      body: JSON.stringify({ query, variables }),
+    },
+  );
+  if (!response.ok) {
+    throw new Error(`Shopify ${response.status}: ${await response.text()}`);
+  }
+
+  const { data, errors } = await response.json();
+  if (errors) {
+    throw new Error(`Shopify: ${JSON.stringify(errors)}`);
+  }
+  return data;
+}
+
+function toPrice(money: ShopifyMoney): Price {
+  return { amount: Number(money.amount), currency: money.currencyCode };
+}
+
+// @todo: Shopify has no generic "specs" field. Vendor and product type are a
+// starting point; swap in your own metafields once you know their namespace.
+function toSpecs(node: ShopifyProduct): Spec[] {
+  const specs: Spec[] = [];
+  if (node.vendor) {
+    specs.push({ label: "Brand", value: node.vendor });
+  }
+  if (node.productType) {
+    specs.push({ label: "Type", value: node.productType });
+  }
+  return specs;
+}
+
+function toProduct(node: ShopifyProduct): Product {
+  const specs = toSpecs(node);
+  const images: string[] = [];
+  for (const image of node.images.nodes) {
+    images.push(image.url);
+  }
+
+  // Walk the variants once, building both the variants and the axes they vary
+  // on. Shopify option names are used as-is for ids, so a variant's
+  // `selectedOptions` maps straight onto `selection`.
+  const options: Option[] = [];
+  const variants: Variant[] = [];
+  for (const variant of node.variants.nodes) {
+    const selection: Record<string, string> = {};
+    for (const selected of variant.selectedOptions) {
+      selection[selected.name] = selected.value;
+
+      let option: Option | undefined;
+      for (const candidate of options) {
+        if (candidate.id === selected.name) {
+          option = candidate;
+          break;
+        }
+      }
+      if (!option) {
+        option = { id: selected.name, label: selected.name, values: [] };
+        options.push(option);
+      }
+
+      let known = false;
+      for (const value of option.values) {
+        if (value.id === selected.value) {
+          known = true;
+          break;
+        }
+      }
+      if (!known) {
+        option.values.push({
+          id: selected.value,
+          label: selected.value,
+          media: variant.image?.url,
+        });
+      }
+    }
+
+    variants.push({
+      id: variant.id,
+      selection,
+      title: variant.title === "Default Title" ? node.title : variant.title,
+      description: node.description,
+      price: toPrice(variant.price),
+      media: variant.image ? [variant.image.url] : images,
+      url: node.onlineStoreUrl ?? undefined,
+      outOfStock: !variant.availableForSale,
+      specs,
+    });
+  }
+
+  // A single-variant product has no axes to pick from.
+  if (variants.length < 2) {
+    options.length = 0;
+  }
+
+  return {
+    id: node.handle,
+    options,
+    variants,
+    card: {
+      title: node.title,
+      description: node.description,
+      price: toPrice(node.priceRange.minVariantPrice),
+      media: images,
+      url: node.onlineStoreUrl ?? undefined,
+      outOfStock: !node.availableForSale,
+      specs,
+    },
+  };
+}
+
+export async function search({
+  keyword,
+  sort,
+  priceRange,
+}: SearchInput): Promise<SearchResult> {
+  // Shopify's search DSL: a bare term matches title, vendor, type and tags;
+  // extra clauses narrow it. @todo: add your own (`tag:`, `product_type:`…).
+  let query = keyword;
+  if (priceRange) {
+    const [min, max] = priceRange.split("-");
+    query += ` variants.price:>=${min} variants.price:<=${max}`;
+  }
+
+  const data = await storefront(
+    `${PRODUCT_FIELDS}
+    query Search($query: String!, $sortKey: ProductSortKeys!, $reverse: Boolean!, $first: Int!) {
+      products(query: $query, sortKey: $sortKey, reverse: $reverse, first: $first) {
+        nodes { ...ProductFields }
+      }
+    }`,
+    {
+      query,
+      sortKey: sort ? "PRICE" : "RELEVANCE",
+      reverse: sort === "price-desc",
+      first: PAGE_SIZE,
+    },
+  );
+
+  const products: Product[] = [];
+  for (const node of data.products.nodes) {
+    products.push(toProduct(node));
+  }
+  // Storefront paginates by cursor and reports no total, so both counts are
+  // left out rather than faked.
+  return { products };
+}
+
+export async function getProducts(ids: string[]): Promise<Product[]> {
+  // One aliased lookup per handle, so the response comes back in the order the
+  // model asked for.
+  const declarations: string[] = [];
+  const fields: string[] = [];
+  const variables: Record<string, string> = {};
+  for (let index = 0; index < ids.length; index++) {
+    declarations.push(`$h${index}: String!`);
+    fields.push(`p${index}: product(handle: $h${index}) { ...ProductFields }`);
+    variables[`h${index}`] = ids[index];
+  }
+
+  const data = await storefront(
+    `${PRODUCT_FIELDS}
+    query Products(${declarations.join(", ")}) {
+      ${fields.join("\n      ")}
+    }`,
+    variables,
+  );
+
+  const products: Product[] = [];
+  for (let index = 0; index < ids.length; index++) {
+    const node = data[`p${index}`];
+    if (node) {
+      products.push(toProduct(node));
+    }
+  }
+  return products;
+}

package/templates/ecom/src/components/product-card.tsx

@@ -30,8 +30,8 @@ export function ProductCard({
 }: ProductCardProps) {
   const { locale } = useUser();
   const labels = useLabels();
-  // Show the first image. @todo: the rest of `media` is available here, e.g.
-  // to cross-fade to media[1] on hover.
+  // Show the first image. @todo: the rest of `media` is available here, e.g. to
+  // swap in media[1] on hover (do not cross-fade, breaks with transparency)
   const cover = media?.[0];
   return (
     <article className={styles.card({ framed: FRAMED })}>

package/templates/ecom/src/components/variant-picker.stories.tsx

@@ -1,6 +1,6 @@
 import { useState } from "react";
 import { initialSelection, type Selection } from "../lib/variants.js";
-import type { Product } from "../tools/render-carousel.js";
+import type { Product } from "../types.js";
 import { VariantPicker } from "./variant-picker";
 
 // A sparse catalog: {white,42} does not exist, so "42" is hard-disabled under

package/templates/ecom/src/components/variant-picker.tsx

@@ -1,7 +1,7 @@
 import { text } from "../design/tokens";
 import { cx } from "../lib/cx";
 import { applyChoice, axisStates, type Selection } from "../lib/variants.js";
-import type { Product } from "../tools/render-carousel.js";
+import type { Product } from "../types.js";
 import { Chip } from "./chip";
 import * as styles from "./variant-picker.css";
 

package/templates/ecom/src/components/view-frame.tsx

@@ -1,5 +1,5 @@
 import type { HTMLAttributes } from "react";
-import { useLayout } from "skybridge/web";
+import { useUser } from "skybridge/web";
 import { darkTheme, lightTheme } from "../design/tokens";
 import { cx } from "../lib/cx";
 import { viewFrame } from "./view-frame.css";
@@ -10,8 +10,8 @@ import { viewFrame } from "./view-frame.css";
  * variables the color contract declares) and paints the base surface + font +
  * content color so descendants inherit from the DS instead of the host page.
  *
- * It follows the host theme via useLayout(). To lock the widget to one palette
- * (e.g. always light), drop useLayout and hardcode the theme class.
+ * It follows the host theme via useUser(). To lock the widget to one palette
+ * (e.g. always light), drop useUser and hardcode the theme class.
  *
  * Keep view entry files thin: render <ViewFrame> at the root and let this carry
  * the theme + base-style boilerplate.
@@ -19,7 +19,7 @@ import { viewFrame } from "./view-frame.css";
 type ViewFrameProps = HTMLAttributes<HTMLDivElement>;
 
 export function ViewFrame({ className, ...rest }: ViewFrameProps) {
-  const { theme } = useLayout();
+  const { theme } = useUser();
   const themeClass = theme === "dark" ? darkTheme : lightTheme;
 
   return <div {...rest} className={cx(themeClass, viewFrame, className)} />;

package/templates/ecom/src/index.ts

@@ -0,0 +1,3 @@
+import { app } from "./server.js";
+
+export default await app.run();

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

@@ -1,4 +1,4 @@
-import type { Product, Variant } from "../tools/render-carousel.js";
+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

package/templates/ecom/src/server.ts

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { McpServer } from "skybridge/server";
+import { Skybridge } from "skybridge/server";
 import { CAROUSEL_RANGE, MIN_SEARCH_ITERATIONS } from "./config.js";
 import {
   renderCarouselDefinition,
@@ -15,29 +15,25 @@ 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: `\
+export const app = new Skybridge({
+  // @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. \
+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. Never call a category unavailable before searching.
+once the carousel renders.
 
 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);
+Speak once it renders, then recommend products in carousel order.`,
+  handler: (server) =>
+    server
+      .registerTool(searchProductsDefinition, searchProductsHandler)
+      .registerTool(renderCarouselDefinition, renderCarouselHandler),
+});
 
-export default await server.run();
-
-export type AppType = typeof server;
+export type AppType = typeof app;