create-skybridge 0.0.0-dev.1b2b016 → 0.0.0-dev.1b3b81f

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

@@ -0,0 +1,254 @@
+import { useEffect, useState } from "react";
+import { useOpenExternal, useSetOpenInAppUrl, useUser } from "skybridge/web";
+import { ExpandableText } from "../../../components/expandable-text";
+import { ImageGallery } from "../../../components/image-gallery";
+import { VariantPicker } from "../../../components/variant-picker";
+import { sprinkles, text } from "../../../design/tokens";
+import { type Labels, useLabels } from "../../../i18n";
+import { cx } from "../../../lib/cx";
+import { formatPrice } from "../../../lib/format";
+import {
+  initialSelection,
+  resolveVariant,
+  type Selection,
+} from "../../../lib/variants.js";
+import type { Product, Variant } from "../../../tools/render-carousel.js";
+import * as styles from "./detail.css";
+
+// Price to show: the resolved variant's price, else the range across variants
+// (or a single price when they agree), else the card price, else a fallback.
+function priceText(
+  product: Product,
+  variantPrice: Product["card"]["price"],
+  locale: string,
+  labels: Labels,
+): string {
+  if (variantPrice) {
+    return formatPrice(variantPrice, locale);
+  }
+  const amounts: number[] = [];
+  let currency = "";
+  for (const variant of product.variants) {
+    if (variant.price) {
+      amounts.push(variant.price.amount);
+      currency = variant.price.currency;
+    }
+  }
+  if (amounts.length > 0) {
+    const min = Math.min(...amounts);
+    const max = Math.max(...amounts);
+    if (min === max) {
+      return formatPrice({ amount: min, currency }, locale);
+    }
+    return `${formatPrice({ amount: min, currency }, locale)} – ${formatPrice({ amount: max, currency }, locale)}`;
+  }
+  if (product.card.price) {
+    return formatPrice(product.card.price, locale);
+  }
+  return labels.priceOnRequest;
+}
+
+// data-llm narrates the variant the user is currently looking at. The full
+// product spec (every variant) is pushed to view state by the carousel
+// orchestrator, so the model can answer beyond what is on screen; this stays
+// scoped to the visible selection.
+function grounding(
+  product: Product,
+  variant: Variant | undefined,
+  title: string,
+  price: string,
+  selection: Selection,
+  unpurchasable: boolean,
+  labels: Labels,
+): string {
+  const parts = [`The user is viewing "${title}" (product id: ${product.id}).`];
+  const chosen: string[] = [];
+  for (const option of product.options) {
+    const valueId = selection[option.id];
+    let label: string | undefined;
+    for (const value of option.values) {
+      if (value.id === valueId) {
+        label = value.label;
+        break;
+      }
+    }
+    if (label === undefined) {
+      // Axis skipped by the shown variant vs simply not picked yet.
+      label =
+        variant != null && variant.selection[option.id] == null
+          ? "not applicable"
+          : "not selected";
+    }
+    chosen.push(`${option.label}: ${label}`);
+  }
+  if (chosen.length > 0) {
+    parts.push(`Selected — ${chosen.join(", ")}.`);
+  }
+  parts.push(`Price: ${price}.`);
+  if (unpurchasable) {
+    // Sold-out real variant vs a combination that does not exist.
+    parts.push(
+      variant != null ? labels.outOfStock : labels.combinationUnavailable,
+    );
+  }
+  return parts.join(" ");
+}
+
+/**
+ * Product detail view, rendered fullscreen over the carousel (see the carousel
+ * orchestrator). Reads a single product from the payload already in `_meta`;
+ * does no fetch. Option choices resolve against the product's sparse variant
+ * list in-place (no remount).
+ */
+export function DetailView({ product }: { product: Product }) {
+  const { locale } = useUser();
+  const labels = useLabels();
+  const openExternal = useOpenExternal();
+  const setOpenInAppUrl = useSetOpenInAppUrl();
+  const [selection, setSelection] = useState<Selection>(() =>
+    initialSelection(product),
+  );
+
+  // The exact variant for the selection; card fields fill in when none
+  // resolves (the applyChoice edge case, or a product with no variants).
+  const shown = resolveVariant(product, selection);
+  const displayTitle = shown?.title ?? product.card.title;
+  const description = shown?.description ?? product.card.description;
+  const media = shown?.media.length ? shown.media : product.card.media;
+  const specs = shown?.specs ?? product.card.specs;
+  // Sold out, or no variant resolved.
+  const unpurchasable = shown ? (shown.outOfStock ?? false) : true;
+  const url = shown?.url ?? product.card.url;
+  // The shown item's id: the resolved variant's SKU, else the product id.
+  const reference = shown?.id ?? product.id;
+  // @todo: read any custom Meta fields you added the same way (shown first,
+  // then card), e.g. `const rating = shown?.rating ?? product.card.rating;`,
+  // then render them in the agreed spot (rating by the title, discount by the
+  // price, badges as chips…).
+
+  const price = priceText(product, shown?.price, locale, labels);
+  // Buy CTA is enabled only for an exact, in-stock variant with a real link
+  // (an empty url would leave the button enabled but dead).
+  const canBuy = shown != null && Boolean(url) && !unpurchasable;
+
+  // Point the host's fullscreen "Open in app" affordance at the selected
+  // variant's page. Apps-SDK only; MCP Apps hosts reject, so ignore that.
+  useEffect(() => {
+    if (url) {
+      setOpenInAppUrl(url).catch(() => {});
+    }
+  }, [url, setOpenInAppUrl]);
+
+  return (
+    <div
+      className={styles.detail}
+      data-llm={grounding(
+        product,
+        shown,
+        displayTitle,
+        price,
+        selection,
+        unpurchasable,
+        labels,
+      )}
+    >
+      {/* Product / variant reference, idiomatically top-right. @todo: move it
+          (e.g. into the info column under the title) or drop it; restyle in
+          detail.css.ts (`reference`). */}
+      <p className={cx(text({ style: "bodyS" }), styles.reference)}>
+        {labels.reference} {reference}
+      </p>
+
+      <div className={styles.grid}>
+        <div className={styles.galleryCell}>
+          {media.length > 0 ? (
+            // Key on the media set so switching to a variant with different
+            // images remounts the gallery fresh (index reset to the first image).
+            <ImageGallery
+              key={media.join("|")}
+              media={media}
+              alt={displayTitle}
+            />
+          ) : null}
+        </div>
+
+        <div className={styles.info}>
+          <h1
+            className={cx(
+              text({ style: "headingS", weight: "medium" }),
+              styles.title,
+            )}
+          >
+            {displayTitle}
+          </h1>
+
+          <p className={cx(text({ style: "headingS" }), styles.price)}>
+            {price}
+          </p>
+
+          <VariantPicker
+            product={product}
+            selection={selection}
+            onChange={setSelection}
+          />
+
+          {description ? <ExpandableText>{description}</ExpandableText> : null}
+
+          {/* Sold-out and unresolved selections stay composable; the CTA locks
+              and its label names the cause. */}
+          <button
+            type="button"
+            className={cx(styles.cta, sprinkles({ mt: "3xs" }))}
+            disabled={!canBuy}
+            onClick={canBuy && url ? () => openExternal(url) : undefined}
+          >
+            {shown
+              ? unpurchasable
+                ? labels.outOfStock
+                : labels.viewOnSite
+              : labels.combinationUnavailable}
+          </button>
+
+          {/* Product facts as a simple list, after the CTA: one "label: value"
+              line per fact (label-less facts show the value alone). This is the
+              visual treatment only; the full spec is already in view state for
+              the model (see the carousel orchestrator), so restyling or dropping
+              it never hides facts from the assistant. @todo: pick the shape that
+              best presents your specs: this list (default), a two-column table,
+              grouped sections, inline chips, etc. */}
+          {specs.length > 0 ? (
+            <section>
+              <h2 className={text({ style: "labelM", weight: "medium" })}>
+                {labels.specifications}
+              </h2>
+              <dl className={styles.specList}>
+                {specs.map((spec) => (
+                  <div
+                    key={`${spec.label ?? ""}:${spec.value}`}
+                    className={styles.specRow}
+                  >
+                    {spec.label ? (
+                      <dt
+                        className={cx(
+                          text({ style: "bodyS" }),
+                          styles.specLabel,
+                        )}
+                      >
+                        {spec.label}:
+                      </dt>
+                    ) : null}
+                    <dd
+                      className={cx(text({ style: "bodyS" }), styles.specValue)}
+                    >
+                      {spec.value}
+                    </dd>
+                  </div>
+                ))}
+              </dl>
+            </section>
+          ) : null}
+        </div>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,234 @@
+import "../../index.css";
+
+import {
+  type ReactNode,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import { useDisplayMode, useViewState } from "skybridge/web";
+import { EmptyState } from "../../components/empty-state";
+import {
+  ProductCard,
+  ProductCardSkeleton,
+} from "../../components/product-card";
+import * as cardStyles from "../../components/product-card.css";
+import { ProductCarousel } from "../../components/product-carousel";
+import { ViewFrame } from "../../components/view-frame";
+import { sprinkles } from "../../design/tokens";
+import { useToolInfo } from "../../helpers.js";
+import { useLabels } from "../../i18n";
+import { formatPrice } from "../../lib/format";
+import type { Product } from "../../tools/render-carousel.js";
+import type { Price, Spec } from "../../types.js";
+import { DetailView } from "./detail";
+
+const SKELETON_COUNT = 4;
+
+// One narration line per on-screen product. `id` ties the card back to its full
+// record in structuredContent.
+function narrate(product: Product, index: number): string {
+  const { card } = product;
+  const price = card.price ? ` - ${formatPrice(card.price)}` : "";
+  const oos = card.outOfStock ? " [out of stock]" : "";
+  return `${index + 1}. ${card.title} (id: ${product.id})${price}${oos}`;
+}
+
+// View state, persisted on the host so an open detail survives a remount (e.g.
+// after a follow-up message). scrollLeft restores the carousel position on the
+// way back; spec is the full product spec (every variant) the model can answer
+// from while the detail is open.
+type VariantSpec = {
+  selection: Record<string, string>; // option label -> chosen value label
+  price?: Price;
+  available: boolean;
+  specs: Spec[];
+};
+type ProductSpec = { id: string; title: string; variants: VariantSpec[] };
+type ViewState = {
+  selectedId: string | null;
+  scrollLeft: number;
+  spec: ProductSpec | null;
+};
+
+// The complete spec of the open product — every variant, not just the visible
+// one — pushed to view state so the model can answer any detail question. The
+// on-screen variant is narrated separately (data-llm, in the detail view). Keep
+// it to a single product; a very large spec trips the view-state size warning.
+function buildProductSpec(product: Product): ProductSpec {
+  const variants: VariantSpec[] = [];
+  for (const variant of product.variants) {
+    const selection: Record<string, string> = {};
+    for (const option of product.options) {
+      const valueId = variant.selection[option.id];
+      if (!valueId) {
+        continue;
+      }
+      let label = valueId;
+      for (const value of option.values) {
+        if (value.id === valueId) {
+          label = value.label;
+          break;
+        }
+      }
+      selection[option.label] = label;
+    }
+    variants.push({
+      selection,
+      price: variant.price,
+      available: !variant.outOfStock,
+      specs: variant.specs,
+    });
+  }
+  return { id: product.id, title: product.card.title, variants };
+}
+
+/**
+ * Carousel view + product detail, in one view. The carousel is the inline
+ * surface; tapping a card opens the detail fullscreen over it (the carousel is
+ * hidden, not unmounted). Both read the full products from `_meta`; the detail
+ * needs no extra fetch.
+ */
+function Carousel() {
+  const { responseMetadata } = useToolInfo<"render-carousel">();
+  const labels = useLabels();
+  const trackRef = useRef<HTMLElement>(null);
+  const [visibleIndices, setVisibleIndices] = useState<number[]>([]);
+  const [mode, setMode] = useDisplayMode();
+  const [nav, setNav] = useViewState<ViewState>({
+    selectedId: null,
+    scrollLeft: 0,
+    spec: null,
+  });
+  // True between requesting fullscreen and the host applying it, so the
+  // collapse-is-back effect below does not fire mid-transition.
+  const enteringRef = useRef(false);
+
+  const selectedId = nav.selectedId;
+  // The detail only mounts once the host is actually fullscreen: rendering the
+  // tall page inside the small inline frame would flash a cramped layout.
+  const showDetail = selectedId != null && mode === "fullscreen";
+
+  // A host-driven exit from fullscreen (the user used host chrome) means "back".
+  useEffect(() => {
+    if (mode === "fullscreen") {
+      enteringRef.current = false;
+      return;
+    }
+    if (selectedId != null && !enteringRef.current) {
+      setNav((prev) => ({ ...prev, selectedId: null, spec: null }));
+    }
+  }, [mode, selectedId, setNav]);
+
+  // Restore carousel scroll when back on the carousel. display:none resets
+  // scrollLeft, so re-apply once it is visible again (layout effect, not mount).
+  useLayoutEffect(() => {
+    if (!showDetail && trackRef.current) {
+      trackRef.current.scrollLeft = nav.scrollLeft;
+    }
+  }, [showDetail, nav.scrollLeft]);
+
+  function openProduct(id: string) {
+    enteringRef.current = true;
+    const list = responseMetadata?.products ?? [];
+    let spec: ProductSpec | null = null;
+    for (const product of list) {
+      if (product.id === id) {
+        spec = buildProductSpec(product);
+        break;
+      }
+    }
+    setNav({
+      selectedId: id,
+      scrollLeft: trackRef.current?.scrollLeft ?? 0,
+      spec,
+    });
+    setMode("fullscreen");
+  }
+
+  // Tool still resolving: reserve the layout with skeleton cards.
+  if (responseMetadata == null) {
+    const skeletons: ReactNode[] = [];
+    for (let i = 0; i < SKELETON_COUNT; i++) {
+      skeletons.push(<ProductCardSkeleton key={i} />);
+    }
+    return (
+      <ViewFrame>
+        <div className={sprinkles({ p: "3xs" })}>
+          <ProductCarousel loading>{skeletons}</ProductCarousel>
+        </div>
+      </ViewFrame>
+    );
+  }
+
+  const products = responseMetadata.products ?? [];
+
+  if (products.length === 0) {
+    return (
+      <ViewFrame>
+        <EmptyState message={labels.noProducts} />
+      </ViewFrame>
+    );
+  }
+
+  // Guard against a stale id (e.g. the model rendered a new carousel while a
+  // detail was open): fall back to the carousel rather than an empty page.
+  const selectedProduct =
+    selectedId != null
+      ? products.find((product) => product.id === selectedId)
+      : undefined;
+  // The detail actually renders only when we have a product to show. Everything
+  // that hides the carousel keys off this, so a stale id shows the carousel, not
+  // a blank page.
+  const detailProduct = showDetail ? selectedProduct : undefined;
+
+  const cards: ReactNode[] = [];
+  for (const [index, product] of products.entries()) {
+    const { card } = product;
+    cards.push(
+      <div key={product.id} className={cardStyles.cardClickable}>
+        <ProductCard
+          // Drop per-card grounding while the detail owns the screen.
+          data-llm={
+            !detailProduct && visibleIndices.includes(index)
+              ? narrate(product, index)
+              : ""
+          }
+          title={card.title}
+          price={card.price}
+          media={card.media}
+          outOfStock={card.outOfStock}
+        />
+        <button
+          type="button"
+          aria-label={card.title}
+          className={cardStyles.cardButton}
+          onClick={() => openProduct(product.id)}
+        />
+      </div>,
+    );
+  }
+
+  const narration = `Carousel of ${products.length} product(s); the user scrolls horizontally. On screen now:`;
+
+  return (
+    <ViewFrame>
+      <div
+        className={sprinkles({ p: "3xs" })}
+        style={{ display: detailProduct ? "none" : undefined }}
+      >
+        <ProductCarousel
+          trackRef={trackRef}
+          onVisibleChange={setVisibleIndices}
+          data-llm={detailProduct ? "" : narration}
+        >
+          {cards}
+        </ProductCarousel>
+      </div>
+      {detailProduct ? <DetailView product={detailProduct} /> : null}
+    </ViewFrame>
+  );
+}
+
+export default Carousel;

package/templates/ecom/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "skybridge/tsconfig",
+
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "types": ["node", "vite/client"]
+  },
+
+  "include": ["src", ".skybridge/**/*.d.ts"]
+}

package/templates/ecom/vite.config.ts

@@ -0,0 +1,8 @@
+import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";
+import react from "@vitejs/plugin-react";
+import { skybridge } from "skybridge/vite";
+import { defineConfig, type PluginOption } from "vite";
+
+export default defineConfig({
+  plugins: [skybridge() as PluginOption, react(), vanillaExtractPlugin()],
+});

package/template/.cursor/mcp.json

@@ -1,7 +0,0 @@
-{
-  "mcpServers": {
-    "local": {
-      "url": "http://localhost:3000/mcp"
-    }
-  }
-}

package/template/.nvmrc

@@ -1 +0,0 @@
-lts/jod

package/template/.vscode/launch.json

@@ -1,16 +0,0 @@
-{
-  "version": "0.0.1",
-  "configurations": [
-    {
-      "name": "Debug MCP Server",
-      "type": "node",
-      "request": "launch",
-      "program": "${workspaceFolder}/dist/index.js",
-      "console": "integratedTerminal",
-      "sourceMaps": true,
-      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
-      "preLaunchTask": "npm: build",
-      "stopOnEntry": false
-    }
-  ]
-}

package/template/.vscode/settings.json

@@ -1,3 +0,0 @@
-{
-  "editor.formatOnSave": true
-}

package/template/.vscode/tasks.json

@@ -1,14 +0,0 @@
-{
-  "version": "2.0.0",
-  "tasks": [
-    {
-      "type": "shell",
-      "command": "npm",
-      "args": ["build"],
-      "group": "build",
-      "label": "npm: build",
-      "detail": "npm build",
-      "problemMatcher": ["$tsc"]
-    }
-  ]
-}

package/template/README.md

@@ -1,116 +0,0 @@
-# ChatGPT Apps SDK Alpic Starter
-
-This repository is a minimal Typescript application demonstrating how to build an OpenAI Apps SDK compatible MCP server with widget rendering in ChatGPT.
-
-![Demo](docs/demo.gif)
-
-## Overview
-
-This project shows how to integrate a Typescript express application with the ChatGPT Apps SDK using the Model Context Protocol (MCP). It includes a working MCP server that exposes tools and resources that can be called from ChatGPT, with responses rendered natively in ChatGPT. It also includes MCP tools without UI widgets.
-
-## Getting Started
-
-### Prerequisites
-
-- Node.js 22+ (see `.nvmrc` for exact version)
-- pnpm (install with `npm install -g pnpm`)
-- Ngrok
-
-### Local Development with Hot Module Replacement (HMR)
-
-This project uses Vite for React widget development with full HMR support, allowing you to see changes in real-time, directly within ChatGPT conversation, without restarting the server.
-
-#### 1. Install
-
-```bash
-pnpm install
-```
-
-#### 2. Start the Development Server
-
-Run the development server from the root directory:
-
-```bash
-pnpm dev
-```
-
-This command starts an Express server on port 3000. This server packages:
-
-- an MCP endpoint on `/mcp` - aka the ChatGPT App Backend
-- a React application on Vite HMR dev server - aka the ChatGPT App Frontend
-
-#### 3. Expose Your Local Server
-
-In a separate terminal, expose your local server using ngrok:
-
-```bash
-ngrok http 3000
-```
-
-Copy the forwarding URL from ngrok output:
-
-```bash
-Forwarding     https://3785c5ddc4b6.ngrok-free.app -> http://localhost:3000
-```
-
-#### 4. Connect to ChatGPT
-
-- Enable **Settings → Connectors → Advanced → Developer mode** in the ChatGPT client
-- Navigate to **Settings → Connectors → Create**
-- Enter your ngrok URL with the `/mcp` path (e.g., `https://3785c5ddc4b6.ngrok-free.app/mcp`)
-- Click **Create**
-
-#### 5. Test Your Integration
-
-- Start a new conversation in ChatGPT
-- Select your newly created connector using **the + button → Your connector**
-- Try prompting the model (e.g., "Show me pikachu details")
-
-#### 6. Develop with HMR
-
-Now you can edit React components in `web` and see changes instantly:
-
-- Make changes to any component
-- Save the file
-- The widget will automatically update in ChatGPT without refreshing or reconnecting
-- The Express server and MCP server continue running without interruption
-
-**Note:** When you modify widget components, changes will be reflected immediately. If you modify MCP server code (in `src/`), you may need to reload your connector in **Settings → Connectors → [Your connector] → Reload**.
-
-## Widget Naming Convention
-
-**Important:** For a widget to work properly, the name of the endpoint in your MCP server must match the file name of the corresponding React component in `web/src/widgets/`.
-
-For example:
-
-- If you create a widget endpoint named `pokemon-card`, you must create a corresponding React component file at `web/src/widgets/pokemon-card.tsx`
-- The endpoint name and the widget file name (without the `.tsx` extension) must be identical
-
-This naming convention allows the system to automatically map widget requests to their corresponding React components.
-
-## Deploy to Production
-
-Use Alpic to deploy your OpenAI App to production.
-
-[![Deploy on Alpic](https://assets.alpic.ai/button.svg)](https://app.alpic.ai/new/clone?repositoryUrl=https%3A%2F%2Fgithub.com%2Falpic-ai%2Fapps-sdk-template)
-
-- In ChatGPT, navigate to **Settings → Connectors → Create** and add your MCP server URL (e.g., `https://your-app-name.alpic.live`)
-
-## Project Structure
-
-```
-.
-├── server/
-│   ├── app.ts          # OpenAI App extension class with widget API implementation
-│   ├── server.ts       # MCP server with tool/resource/prompt registration
-│   └── index.ts        # Express server definition
-└── web/
-    └── src/
-        └── widgets/    # React widget components (must match endpoint names)
-```
-
-## Resources
-
-- [Apps SDK Documentation](https://developers.openai.com/apps-sdk)
-- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
-- [Alpic Documentation](https://docs.alpic.ai/)