create-skybridge 0.0.0-dev.e28dbb6 → 0.0.0-dev.e2c53a4

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 * as cardStyles from "../../components/product-card.css";
+import {
+  ProductCard,
+  ProductCardSkeleton,
+} from "../../components/product-card";
+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 { Attribute, Price } 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;
+  attributes: Attribute[];
+};
+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,
+      attributes: variant.attributes,
+    });
+  }
+  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/dist/index.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/index.test.js

@@ -1,33 +0,0 @@
-import { randomBytes } from "node:crypto";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { init } from "./index.js";
-describe("create-skybridge", () => {
-    let tempDirName;
-    beforeEach(() => {
-        tempDirName = `test-${randomBytes(2).toString("hex")}`;
-    });
-    afterEach(async () => {
-        await fs.rm(path.join(process.cwd(), tempDirName), {
-            recursive: true,
-            force: true,
-        });
-    });
-    it("should copy the template", { timeout: 10000 }, async () => {
-        const name = `../../${tempDirName}//project$`;
-        await init([name]);
-        await fs.access(path.join(process.cwd(), tempDirName, "project", ".gitignore"));
-        expect(fs.access(path.join(process.cwd(), tempDirName, "project", ".npmrc"))).rejects.toThrowError();
-    });
-    it("should download template from repo", { timeout: 10000 }, async () => {
-        const name = `../../${tempDirName}//project$`;
-        await init([
-            name,
-            "--repo",
-            "github:alpic-ai/skybridge/examples/ecom-carousel",
-        ]);
-        await fs.access(path.join(process.cwd(), tempDirName, "project", ".gitignore"));
-        expect(fs.access(path.join(process.cwd(), tempDirName, "project", ".npmrc"))).rejects.toThrowError();
-    });
-});

package/template/README.md

@@ -1,97 +0,0 @@
-# Skybridge Starter
-
-A minimal TypeScript template for building MCP and ChatGPT Apps with the [Skybridge](https://docs.skybridge.tech/home) framework.
-
-## Getting Started
-
-### Prerequisites
-
-- Node.js 24+
-- HTTP tunnel such as [Alpic tunnel](https://docs.alpic.ai/cli/tunnel) if you want to test with remote MCP hosts like ChatGPT or Claude.ai.
-
-### Local Development
-
-#### 1. Install
-
-```bash
-npm install
-# or
-yarn install
-# or
-pnpm install
-# or
-bun install
-```
-
-#### 2. Start your local server
-
-Run the development server from the root directory:
-
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
-```
-
-This command starts:
-- Your MCP server at `http://localhost:3000/mcp`.
-- Skybridge DevTools UI at `http://localhost:3000/`.
-
-#### 3. Project structure
-
-```
-├── server/
-│   └── src/
-│       └── index.ts      # Server entry point
-├── web/
-│   ├── src/
-│   │   ├── widgets/      # React components (one per widget)
-│   │   ├── helpers.ts    # Shared utilities
-│   │   └── index.css     # Global styles
-│   └── vite.config.ts
-├── alpic.json            # Deployment config
-├── nodemon.json          # Dev server config
-└── package.json
-```
-
-### Create your first widget
-
-#### 1. Add a new widget
-
-- Register a widget in `server/src/server.ts` with a unique name (e.g., `my-widget`) using [`registerWidget`](https://docs.skybridge.tech/api-reference/register-widget)
-- Create a matching React component at `web/src/widgets/my-widget.tsx`. **The file name must match the widget name exactly**.
-
-#### 2. Edit widgets with Hot Module Replacement (HMR)
-
-Edit and save components in `web/src/widgets/` — changes will appear instantly inside your App.
-
-#### 3. Edit server code
-
-Modify files in `server/` and refresh the connection with your testing MCP Client to see the changes.
-
-### Testing your App
-
-You can test your App locally by using our DevTools UI on `localhost:3000` while running the `pnpm dev` command.
-
-To test your app with other MCP Clients like ChatGPT, Claude or VSCode, see [Testing Your App](https://docs.skybridge.tech/quickstart/test-your-app).
-
-
-## Deploy to Production
-
-Skybridge is infrastructure vendor agnostic, and your app can be deployed on any cloud platform supporting MCP.
-
-The simplest way to deploy your App in minutes is [Alpic](https://alpic.ai/).
-1. Create an account on [Alpic platform](https://app.alpic.ai/). 
-2. Connect your GitHub repository to automatically deploy at each commit. 
-3. Use your remote App URL to connect it to MCP Clients, or use the Alpic Playground to easily test your App.
-
-## Resources
-- [Skybridge Documentation](https://docs.skybridge.tech/)
-- [Apps SDK Documentation](https://developers.openai.com/apps-sdk)
-- [MCP Apps Documentation](https://github.com/modelcontextprotocol/ext-apps/tree/main)
-- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
-- [Alpic Documentation](https://docs.alpic.ai/)

package/template/node_modules/.bin/alpic

@@ -1,21 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*|*MINGW*|*MSYS*)
-        if command -v cygpath > /dev/null 2>&1; then
-            basedir=`cygpath -w "$basedir"`
-        fi
-    ;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.104.1_@opentelemetry+api@1.9.0_arktype@2.1.27_rxjs@7.8.2_typescript@6.0.2/node_modules/alpic/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.104.1_@opentelemetry+api@1.9.0_arktype@2.1.27_rxjs@7.8.2_typescript@6.0.2/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.104.1_@opentelemetry+api@1.9.0_arktype@2.1.27_rxjs@7.8.2_typescript@6.0.2/node_modules/alpic/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.104.1_@opentelemetry+api@1.9.0_arktype@2.1.27_rxjs@7.8.2_typescript@6.0.2/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" "$@"
-else
-  exec node  "$basedir/../alpic/bin/run.js" "$@"
-fi

package/template/node_modules/.bin/sb

@@ -1,21 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*|*MINGW*|*MSYS*)
-        if command -v cygpath > /dev/null 2>&1; then
-            basedir=`cygpath -w "$basedir"`
-        fi
-    ;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.35.14_@modelcontextprotocol+sdk@1.29.0_zod@4.3.6__@skybridge+devtools@0.35._9ddb2dfa56e61c7e1e71871404a50ada/node_modules/skybridge/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.35.14_@modelcontextprotocol+sdk@1.29.0_zod@4.3.6__@skybridge+devtools@0.35._9ddb2dfa56e61c7e1e71871404a50ada/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.35.14_@modelcontextprotocol+sdk@1.29.0_zod@4.3.6__@skybridge+devtools@0.35._9ddb2dfa56e61c7e1e71871404a50ada/node_modules/skybridge/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.35.14_@modelcontextprotocol+sdk@1.29.0_zod@4.3.6__@skybridge+devtools@0.35._9ddb2dfa56e61c7e1e71871404a50ada/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../skybridge/bin/run.js" "$@"
-else
-  exec node  "$basedir/../skybridge/bin/run.js" "$@"
-fi

package/template/node_modules/.bin/skybridge

@@ -1,21 +0,0 @@
-#!/bin/sh
-basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
-
-case `uname` in
-    *CYGWIN*|*MINGW*|*MSYS*)
-        if command -v cygpath > /dev/null 2>&1; then
-            basedir=`cygpath -w "$basedir"`
-        fi
-    ;;
-esac
-
-if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.35.14_@modelcontextprotocol+sdk@1.29.0_zod@4.3.6__@skybridge+devtools@0.35._9ddb2dfa56e61c7e1e71871404a50ada/node_modules/skybridge/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.35.14_@modelcontextprotocol+sdk@1.29.0_zod@4.3.6__@skybridge+devtools@0.35._9ddb2dfa56e61c7e1e71871404a50ada/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.35.14_@modelcontextprotocol+sdk@1.29.0_zod@4.3.6__@skybridge+devtools@0.35._9ddb2dfa56e61c7e1e71871404a50ada/node_modules/skybridge/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.35.14_@modelcontextprotocol+sdk@1.29.0_zod@4.3.6__@skybridge+devtools@0.35._9ddb2dfa56e61c7e1e71871404a50ada/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
-fi
-if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../skybridge/bin/run.js" "$@"
-else
-  exec node  "$basedir/../skybridge/bin/run.js" "$@"
-fi

package/template/package.json

@@ -1,34 +0,0 @@
-{
-  "name": "apps-sdk-template",
-  "version": "0.0.1",
-  "private": true,
-  "description": "Alpic MCP Server Template",
-  "type": "module",
-  "scripts": {
-    "dev": "skybridge dev",
-    "build": "skybridge build",
-    "start": "skybridge start",
-    "deploy": "alpic deploy"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "skybridge": ">=0.35.14 <1.0.0",
-    "vite": "^8.0.3",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@skybridge/devtools": ">=0.35.14 <1.0.0",
-    "@types/react": "^19.2.14",
-    "@types/node": "^24.12.0",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^6.0.1",
-    "alpic": "^1.104.1",
-    "tsx": "^4.21.0",
-    "typescript": "^6.0.2"
-  },
-  "engines": {
-    "node": ">=24.14.1"
-  }
-}

package/template/server/src/index.ts

@@ -1,62 +0,0 @@
-import { McpServer } from "skybridge/server";
-import { z } from "zod";
-
-const Answers = [
-  "As I see it, yes",
-  "Don't count on it",
-  "It is certain",
-  "It is decidedly so",
-  "Most likely",
-  "My reply is no",
-  "My sources say no",
-  "Outlook good",
-  "Outlook not so good",
-  "Signs point to yes",
-  "Very doubtful",
-  "Without a doubt",
-  "Yes definitely",
-  "Yes",
-  "You may rely on it",
-];
-
-const server = new McpServer(
-  {
-    name: "alpic-openai-app",
-    version: "0.0.1",
-  },
-  { capabilities: {} },
-).registerWidget(
-  "magic-8-ball",
-  {
-    description: "Magic 8 Ball",
-  },
-  {
-    description: "For fortune-telling or seeking advice.",
-    inputSchema: {
-      question: z.string().describe("The user question."),
-    },
-  },
-  async ({ question }) => {
-    try {
-      // deterministic answer
-      const hash = question
-        .split("")
-        .reduce((acc, char) => acc + char.charCodeAt(0), 0);
-      const answer = Answers[hash % Answers.length];
-      return {
-        structuredContent: { answer },
-        content: [],
-        isError: false,
-      };
-    } catch (error) {
-      return {
-        content: [{ type: "text", text: `Error: ${error}` }],
-        isError: true,
-      };
-    }
-  },
-);
-
-server.run();
-
-export type AppType = typeof server;

package/template/tsconfig.json

@@ -1,13 +0,0 @@
-{
-  "extends": "skybridge/tsconfig",
-
-  "compilerOptions": {
-    "outDir": "dist",
-    "types": ["node", "vite/client"],
-    "paths": {
-      "@/*": ["./web/src/*"]
-    }
-  },
-
-  "include": ["server/src", "web/src"]
-}

package/template/web/src/helpers.ts

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