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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (146) hide show
  1. package/dist/index.js +342 -210
  2. package/package.json +9 -8
  3. package/templates/blank/.dockerignore +4 -0
  4. package/templates/blank/AGENTS.md +1 -0
  5. package/templates/blank/Dockerfile +53 -0
  6. package/templates/blank/README.md +92 -0
  7. package/{template → templates/blank}/_gitignore +3 -1
  8. package/templates/blank/node_modules/.bin/alpic +21 -0
  9. package/templates/blank/node_modules/.bin/sb +21 -0
  10. package/templates/blank/node_modules/.bin/skybridge +21 -0
  11. package/{template → templates/blank}/node_modules/.bin/tsc +2 -2
  12. package/{template → templates/blank}/node_modules/.bin/tsserver +2 -2
  13. package/{template → templates/blank}/node_modules/.bin/tsx +2 -2
  14. package/templates/blank/node_modules/.bin/vite +21 -0
  15. package/templates/blank/package.json +30 -0
  16. package/templates/blank/src/helpers.ts +4 -0
  17. package/templates/blank/src/server.ts +16 -0
  18. package/templates/blank/tsconfig.json +5 -0
  19. package/templates/blank/vite.config.ts +12 -0
  20. package/templates/demo/.dockerignore +4 -0
  21. package/templates/demo/AGENTS.md +1 -0
  22. package/templates/demo/Dockerfile +53 -0
  23. package/templates/demo/README.md +95 -0
  24. package/templates/demo/_gitignore +7 -0
  25. package/templates/demo/alpic.json +3 -0
  26. package/templates/demo/node_modules/.bin/alpic +21 -0
  27. package/templates/demo/node_modules/.bin/sb +21 -0
  28. package/templates/demo/node_modules/.bin/skybridge +21 -0
  29. package/templates/demo/node_modules/.bin/tsc +21 -0
  30. package/templates/demo/node_modules/.bin/tsserver +21 -0
  31. package/templates/demo/node_modules/.bin/tsx +21 -0
  32. package/templates/demo/node_modules/.bin/vite +21 -0
  33. package/templates/demo/package.json +42 -0
  34. package/templates/demo/src/helpers.ts +4 -0
  35. package/templates/demo/src/index.css +59 -0
  36. package/templates/demo/src/server.ts +94 -0
  37. package/templates/demo/src/views/components/doc-link.tsx +22 -0
  38. package/templates/demo/src/views/components/doc.tsx +21 -0
  39. package/templates/demo/src/views/components/nav.tsx +31 -0
  40. package/templates/demo/src/views/components/progress.tsx +35 -0
  41. package/templates/demo/src/views/components/steps/outro.tsx +68 -0
  42. package/templates/demo/src/views/components/steps/state.tsx +47 -0
  43. package/templates/demo/src/views/components/steps/tool-call.tsx +53 -0
  44. package/templates/demo/src/views/components/steps/tool-output.tsx +40 -0
  45. package/templates/demo/src/views/images/mascot/beret.png +0 -0
  46. package/templates/demo/src/views/images/mascot/chapka.png +0 -0
  47. package/templates/demo/src/views/images/mascot/cowboy-hat.png +0 -0
  48. package/templates/demo/src/views/images/mascot/fez.png +0 -0
  49. package/templates/demo/src/views/images/mascot/jester-hat.png +0 -0
  50. package/templates/demo/src/views/images/mascot/mitre.png +0 -0
  51. package/templates/demo/src/views/images/mascot/non-la.png +0 -0
  52. package/templates/demo/src/views/images/mascot/original.png +0 -0
  53. package/templates/demo/src/views/images/mascot/propeller-beanie.png +0 -0
  54. package/templates/demo/src/views/images/mascot/ski-mask.png +0 -0
  55. package/templates/demo/src/views/images/mascot/sombrero.png +0 -0
  56. package/templates/demo/src/views/images/mascot/top-hat.png +0 -0
  57. package/templates/demo/src/views/images/mascot/viking-helmet.png +0 -0
  58. package/templates/demo/src/views/onboarding.tsx +63 -0
  59. package/templates/demo/src/views/use-mascot.ts +60 -0
  60. package/templates/demo/tsconfig.json +11 -0
  61. package/templates/demo/vite.config.ts +20 -0
  62. package/templates/ecom/.dockerignore +4 -0
  63. package/templates/ecom/.env.template +7 -0
  64. package/templates/ecom/.ladle/components.tsx +26 -0
  65. package/templates/ecom/.ladle/config.mjs +11 -0
  66. package/templates/ecom/.ladle/vite.config.ts +11 -0
  67. package/templates/ecom/AGENTS.md +2 -0
  68. package/templates/ecom/Dockerfile +53 -0
  69. package/templates/ecom/README.md +92 -0
  70. package/templates/ecom/_gitignore +9 -0
  71. package/templates/ecom/alpic.json +3 -0
  72. package/templates/ecom/node_modules/.bin/alpic +21 -0
  73. package/templates/ecom/node_modules/.bin/ladle +21 -0
  74. package/templates/ecom/node_modules/.bin/sb +21 -0
  75. package/templates/ecom/node_modules/.bin/skybridge +21 -0
  76. package/templates/ecom/node_modules/.bin/tsc +21 -0
  77. package/templates/ecom/node_modules/.bin/tsserver +21 -0
  78. package/templates/ecom/node_modules/.bin/tsx +21 -0
  79. package/templates/ecom/node_modules/.bin/vite +21 -0
  80. package/templates/ecom/package.json +42 -0
  81. package/templates/ecom/src/catalog/index.ts +19 -0
  82. package/templates/ecom/src/catalog/mock.ts +134 -0
  83. package/templates/ecom/src/catalog/shopify.ts +264 -0
  84. package/templates/ecom/src/components/chip.css.ts +63 -0
  85. package/templates/ecom/src/components/chip.stories.tsx +27 -0
  86. package/templates/ecom/src/components/chip.tsx +49 -0
  87. package/templates/ecom/src/components/empty-state.stories.tsx +3 -0
  88. package/templates/ecom/src/components/empty-state.tsx +12 -0
  89. package/templates/ecom/src/components/expandable-text.css.ts +49 -0
  90. package/templates/ecom/src/components/expandable-text.stories.tsx +20 -0
  91. package/templates/ecom/src/components/expandable-text.tsx +53 -0
  92. package/templates/ecom/src/components/image-gallery.css.ts +172 -0
  93. package/templates/ecom/src/components/image-gallery.stories.tsx +30 -0
  94. package/templates/ecom/src/components/image-gallery.tsx +163 -0
  95. package/templates/ecom/src/components/product-card.css.ts +159 -0
  96. package/templates/ecom/src/components/product-card.stories.tsx +58 -0
  97. package/templates/ecom/src/components/product-card.tsx +102 -0
  98. package/templates/ecom/src/components/product-carousel.css.ts +134 -0
  99. package/templates/ecom/src/components/product-carousel.stories.tsx +64 -0
  100. package/templates/ecom/src/components/product-carousel.tsx +202 -0
  101. package/templates/ecom/src/components/variant-picker.css.ts +27 -0
  102. package/templates/ecom/src/components/variant-picker.stories.tsx +67 -0
  103. package/templates/ecom/src/components/variant-picker.tsx +70 -0
  104. package/templates/ecom/src/components/view-frame.css.ts +22 -0
  105. package/templates/ecom/src/components/view-frame.tsx +27 -0
  106. package/templates/ecom/src/config.ts +12 -0
  107. package/templates/ecom/src/design/contract.css.ts +39 -0
  108. package/templates/ecom/src/design/fonts.css +15 -0
  109. package/templates/ecom/src/design/primitives.css.ts +101 -0
  110. package/templates/ecom/src/design/recipes/typography.css.ts +75 -0
  111. package/templates/ecom/src/design/sprinkles.css.ts +128 -0
  112. package/templates/ecom/src/design/themes/dark.css.ts +36 -0
  113. package/templates/ecom/src/design/themes/light.css.ts +36 -0
  114. package/templates/ecom/src/design/tokens.ts +8 -0
  115. package/templates/ecom/src/helpers.ts +4 -0
  116. package/templates/ecom/src/i18n.ts +35 -0
  117. package/templates/ecom/src/index.css +9 -0
  118. package/templates/ecom/src/lib/cx.ts +9 -0
  119. package/templates/ecom/src/lib/format.ts +9 -0
  120. package/templates/ecom/src/lib/variants.ts +150 -0
  121. package/templates/ecom/src/server.ts +43 -0
  122. package/templates/ecom/src/tools/render-carousel.ts +161 -0
  123. package/templates/ecom/src/tools/search-products.ts +196 -0
  124. package/templates/ecom/src/types.ts +87 -0
  125. package/templates/ecom/src/views/carousel/detail/detail.css.ts +115 -0
  126. package/templates/ecom/src/views/carousel/detail/detail.stories.tsx +133 -0
  127. package/templates/ecom/src/views/carousel/detail/index.tsx +254 -0
  128. package/templates/ecom/src/views/carousel/index.tsx +233 -0
  129. package/templates/ecom/tsconfig.json +11 -0
  130. package/templates/ecom/vite.config.ts +8 -0
  131. package/dist/index.test.d.ts +0 -1
  132. package/dist/index.test.js +0 -33
  133. package/template/AGENTS.md +0 -1
  134. package/template/README.md +0 -97
  135. package/template/node_modules/.bin/alpic +0 -21
  136. package/template/node_modules/.bin/sb +0 -21
  137. package/template/node_modules/.bin/skybridge +0 -21
  138. package/template/node_modules/.bin/vite +0 -21
  139. package/template/package.json +0 -33
  140. package/template/server/src/index.ts +0 -62
  141. package/template/tsconfig.json +0 -9
  142. package/template/web/src/helpers.ts +0 -4
  143. package/template/web/src/index.css +0 -154
  144. package/template/web/src/widgets/magic-8-ball.tsx +0 -27
  145. package/template/web/vite.config.ts +0 -15
  146. /package/{template → templates/blank}/alpic.json +0 -0
@@ -0,0 +1,254 @@
1
+ import { useEffect, useState } from "react";
2
+ import { useOpenExternal, useSetOpenInAppUrl, useUser } from "skybridge/web";
3
+ import { ExpandableText } from "../../../components/expandable-text";
4
+ import { ImageGallery } from "../../../components/image-gallery";
5
+ import { VariantPicker } from "../../../components/variant-picker";
6
+ import { sprinkles, text } from "../../../design/tokens";
7
+ import { type Labels, useLabels } from "../../../i18n";
8
+ import { cx } from "../../../lib/cx";
9
+ import { formatPrice } from "../../../lib/format";
10
+ import {
11
+ initialSelection,
12
+ resolveVariant,
13
+ type Selection,
14
+ } from "../../../lib/variants.js";
15
+ import type { Product, Variant } from "../../../types.js";
16
+ import * as styles from "./detail.css";
17
+
18
+ // Price to show: the resolved variant's price, else the range across variants
19
+ // (or a single price when they agree), else the card price, else a fallback.
20
+ function priceText(
21
+ product: Product,
22
+ variantPrice: Product["card"]["price"],
23
+ locale: string,
24
+ labels: Labels,
25
+ ): string {
26
+ if (variantPrice) {
27
+ return formatPrice(variantPrice, locale);
28
+ }
29
+ const amounts: number[] = [];
30
+ let currency = "";
31
+ for (const variant of product.variants) {
32
+ if (variant.price) {
33
+ amounts.push(variant.price.amount);
34
+ currency = variant.price.currency;
35
+ }
36
+ }
37
+ if (amounts.length > 0) {
38
+ const min = Math.min(...amounts);
39
+ const max = Math.max(...amounts);
40
+ if (min === max) {
41
+ return formatPrice({ amount: min, currency }, locale);
42
+ }
43
+ return `${formatPrice({ amount: min, currency }, locale)} – ${formatPrice({ amount: max, currency }, locale)}`;
44
+ }
45
+ if (product.card.price) {
46
+ return formatPrice(product.card.price, locale);
47
+ }
48
+ return labels.priceOnRequest;
49
+ }
50
+
51
+ // data-llm narrates the variant the user is currently looking at. The full
52
+ // product spec (every variant) is pushed to view state by the carousel
53
+ // orchestrator, so the model can answer beyond what is on screen; this stays
54
+ // scoped to the visible selection.
55
+ function grounding(
56
+ product: Product,
57
+ variant: Variant | undefined,
58
+ title: string,
59
+ price: string,
60
+ selection: Selection,
61
+ unpurchasable: boolean,
62
+ labels: Labels,
63
+ ): string {
64
+ const parts = [`The user is viewing "${title}" (product id: ${product.id}).`];
65
+ const chosen: string[] = [];
66
+ for (const option of product.options) {
67
+ const valueId = selection[option.id];
68
+ let label: string | undefined;
69
+ for (const value of option.values) {
70
+ if (value.id === valueId) {
71
+ label = value.label;
72
+ break;
73
+ }
74
+ }
75
+ if (label === undefined) {
76
+ // Axis skipped by the shown variant vs simply not picked yet.
77
+ label =
78
+ variant != null && variant.selection[option.id] == null
79
+ ? "not applicable"
80
+ : "not selected";
81
+ }
82
+ chosen.push(`${option.label}: ${label}`);
83
+ }
84
+ if (chosen.length > 0) {
85
+ parts.push(`Selected — ${chosen.join(", ")}.`);
86
+ }
87
+ parts.push(`Price: ${price}.`);
88
+ if (unpurchasable) {
89
+ // Sold-out real variant vs a combination that does not exist.
90
+ parts.push(
91
+ variant != null ? labels.outOfStock : labels.combinationUnavailable,
92
+ );
93
+ }
94
+ return parts.join(" ");
95
+ }
96
+
97
+ /**
98
+ * Product detail view, rendered fullscreen over the carousel (see the carousel
99
+ * orchestrator). Reads a single product from the payload already in `_meta`;
100
+ * does no fetch. Option choices resolve against the product's sparse variant
101
+ * list in-place (no remount).
102
+ */
103
+ export function DetailView({ product }: { product: Product }) {
104
+ const { locale } = useUser();
105
+ const labels = useLabels();
106
+ const openExternal = useOpenExternal();
107
+ const setOpenInAppUrl = useSetOpenInAppUrl();
108
+ const [selection, setSelection] = useState<Selection>(() =>
109
+ initialSelection(product),
110
+ );
111
+
112
+ // The exact variant for the selection; card fields fill in when none
113
+ // resolves (the applyChoice edge case, or a product with no variants).
114
+ const shown = resolveVariant(product, selection);
115
+ const displayTitle = shown?.title ?? product.card.title;
116
+ const description = shown?.description ?? product.card.description;
117
+ const media = shown?.media.length ? shown.media : product.card.media;
118
+ const specs = shown?.specs ?? product.card.specs;
119
+ // Sold out, or no variant resolved.
120
+ const unpurchasable = shown ? (shown.outOfStock ?? false) : true;
121
+ const url = shown?.url ?? product.card.url;
122
+ // The shown item's id: the resolved variant's SKU, else the product id.
123
+ const reference = shown?.id ?? product.id;
124
+ // @todo: read any custom Meta fields you added the same way (shown first,
125
+ // then card), e.g. `const rating = shown?.rating ?? product.card.rating;`,
126
+ // then render them in the agreed spot (rating by the title, discount by the
127
+ // price, badges as chips…).
128
+
129
+ const price = priceText(product, shown?.price, locale, labels);
130
+ // Buy CTA is enabled only for an exact, in-stock variant with a real link
131
+ // (an empty url would leave the button enabled but dead).
132
+ const canBuy = shown != null && Boolean(url) && !unpurchasable;
133
+
134
+ // Point the host's fullscreen "Open in app" affordance at the selected
135
+ // variant's page. Apps-SDK only; MCP Apps hosts reject, so ignore that.
136
+ useEffect(() => {
137
+ if (url) {
138
+ setOpenInAppUrl(url).catch(() => {});
139
+ }
140
+ }, [url, setOpenInAppUrl]);
141
+
142
+ return (
143
+ <div
144
+ className={styles.detail}
145
+ data-llm={grounding(
146
+ product,
147
+ shown,
148
+ displayTitle,
149
+ price,
150
+ selection,
151
+ unpurchasable,
152
+ labels,
153
+ )}
154
+ >
155
+ {/* Product / variant reference, idiomatically top-right. @todo: move it
156
+ (e.g. into the info column under the title) or drop it; restyle in
157
+ detail.css.ts (`reference`). */}
158
+ <p className={cx(text({ style: "bodyS" }), styles.reference)}>
159
+ {labels.reference} {reference}
160
+ </p>
161
+
162
+ <div className={styles.grid}>
163
+ <div className={styles.galleryCell}>
164
+ {media.length > 0 ? (
165
+ // Key on the media set so switching to a variant with different
166
+ // images remounts the gallery fresh (index reset to the first image).
167
+ <ImageGallery
168
+ key={media.join("|")}
169
+ media={media}
170
+ alt={displayTitle}
171
+ />
172
+ ) : null}
173
+ </div>
174
+
175
+ <div className={styles.info}>
176
+ <h1
177
+ className={cx(
178
+ text({ style: "headingS", weight: "medium" }),
179
+ styles.title,
180
+ )}
181
+ >
182
+ {displayTitle}
183
+ </h1>
184
+
185
+ <p className={cx(text({ style: "headingS" }), styles.price)}>
186
+ {price}
187
+ </p>
188
+
189
+ <VariantPicker
190
+ product={product}
191
+ selection={selection}
192
+ onChange={setSelection}
193
+ />
194
+
195
+ {description ? <ExpandableText>{description}</ExpandableText> : null}
196
+
197
+ {/* Sold-out and unresolved selections stay composable; the CTA locks
198
+ and its label names the cause. */}
199
+ <button
200
+ type="button"
201
+ className={cx(styles.cta, sprinkles({ mt: "3xs" }))}
202
+ disabled={!canBuy}
203
+ onClick={canBuy && url ? () => openExternal(url) : undefined}
204
+ >
205
+ {shown
206
+ ? unpurchasable
207
+ ? labels.outOfStock
208
+ : labels.viewOnSite
209
+ : labels.combinationUnavailable}
210
+ </button>
211
+
212
+ {/* Product facts as a simple list, after the CTA: one "label: value"
213
+ line per fact (label-less facts show the value alone). This is the
214
+ visual treatment only; the full spec is already in view state for
215
+ the model (see the carousel orchestrator), so restyling or dropping
216
+ it never hides facts from the assistant. @todo: pick the shape that
217
+ best presents your specs: this list (default), a two-column table,
218
+ grouped sections, inline chips, etc. */}
219
+ {specs.length > 0 ? (
220
+ <section>
221
+ <h2 className={text({ style: "labelM", weight: "medium" })}>
222
+ {labels.specifications}
223
+ </h2>
224
+ <dl className={styles.specList}>
225
+ {specs.map((spec) => (
226
+ <div
227
+ key={`${spec.label ?? ""}:${spec.value}`}
228
+ className={styles.specRow}
229
+ >
230
+ {spec.label ? (
231
+ <dt
232
+ className={cx(
233
+ text({ style: "bodyS" }),
234
+ styles.specLabel,
235
+ )}
236
+ >
237
+ {spec.label}:
238
+ </dt>
239
+ ) : null}
240
+ <dd
241
+ className={cx(text({ style: "bodyS" }), styles.specValue)}
242
+ >
243
+ {spec.value}
244
+ </dd>
245
+ </div>
246
+ ))}
247
+ </dl>
248
+ </section>
249
+ ) : null}
250
+ </div>
251
+ </div>
252
+ </div>
253
+ );
254
+ }
@@ -0,0 +1,233 @@
1
+ import "../../index.css";
2
+
3
+ import {
4
+ type ReactNode,
5
+ useEffect,
6
+ useLayoutEffect,
7
+ useRef,
8
+ useState,
9
+ } from "react";
10
+ import { useDisplayMode, useViewState } from "skybridge/web";
11
+ import { EmptyState } from "../../components/empty-state";
12
+ import {
13
+ ProductCard,
14
+ ProductCardSkeleton,
15
+ } from "../../components/product-card";
16
+ import * as cardStyles from "../../components/product-card.css";
17
+ import { ProductCarousel } from "../../components/product-carousel";
18
+ import { ViewFrame } from "../../components/view-frame";
19
+ import { sprinkles } from "../../design/tokens";
20
+ import { useToolInfo } from "../../helpers.js";
21
+ import { useLabels } from "../../i18n";
22
+ import { formatPrice } from "../../lib/format";
23
+ import type { Price, Product, Spec } from "../../types.js";
24
+ import { DetailView } from "./detail";
25
+
26
+ const SKELETON_COUNT = 4;
27
+
28
+ // One narration line per on-screen product. `id` ties the card back to its full
29
+ // record in structuredContent.
30
+ function narrate(product: Product, index: number): string {
31
+ const { card } = product;
32
+ const price = card.price ? ` - ${formatPrice(card.price)}` : "";
33
+ const oos = card.outOfStock ? " [out of stock]" : "";
34
+ return `${index + 1}. ${card.title} (id: ${product.id})${price}${oos}`;
35
+ }
36
+
37
+ // View state, persisted on the host so an open detail survives a remount (e.g.
38
+ // after a follow-up message). scrollLeft restores the carousel position on the
39
+ // way back; spec is the full product spec (every variant) the model can answer
40
+ // from while the detail is open.
41
+ type VariantSpec = {
42
+ selection: Record<string, string>; // option label -> chosen value label
43
+ price?: Price;
44
+ available: boolean;
45
+ specs: Spec[];
46
+ };
47
+ type ProductSpec = { id: string; title: string; variants: VariantSpec[] };
48
+ type ViewState = {
49
+ selectedId: string | null;
50
+ scrollLeft: number;
51
+ spec: ProductSpec | null;
52
+ };
53
+
54
+ // The complete spec of the open product — every variant, not just the visible
55
+ // one — pushed to view state so the model can answer any detail question. The
56
+ // on-screen variant is narrated separately (data-llm, in the detail view). Keep
57
+ // it to a single product; a very large spec trips the view-state size warning.
58
+ function buildProductSpec(product: Product): ProductSpec {
59
+ const variants: VariantSpec[] = [];
60
+ for (const variant of product.variants) {
61
+ const selection: Record<string, string> = {};
62
+ for (const option of product.options) {
63
+ const valueId = variant.selection[option.id];
64
+ if (!valueId) {
65
+ continue;
66
+ }
67
+ let label = valueId;
68
+ for (const value of option.values) {
69
+ if (value.id === valueId) {
70
+ label = value.label;
71
+ break;
72
+ }
73
+ }
74
+ selection[option.label] = label;
75
+ }
76
+ variants.push({
77
+ selection,
78
+ price: variant.price,
79
+ available: !variant.outOfStock,
80
+ specs: variant.specs,
81
+ });
82
+ }
83
+ return { id: product.id, title: product.card.title, variants };
84
+ }
85
+
86
+ /**
87
+ * Carousel view + product detail, in one view. The carousel is the inline
88
+ * surface; tapping a card opens the detail fullscreen over it (the carousel is
89
+ * hidden, not unmounted). Both read the full products from `_meta`; the detail
90
+ * needs no extra fetch.
91
+ */
92
+ function Carousel() {
93
+ const { responseMetadata } = useToolInfo<"render-carousel">();
94
+ const labels = useLabels();
95
+ const trackRef = useRef<HTMLElement>(null);
96
+ const [visibleIndices, setVisibleIndices] = useState<number[]>([]);
97
+ const [mode, setMode] = useDisplayMode();
98
+ const [nav, setNav] = useViewState<ViewState>({
99
+ selectedId: null,
100
+ scrollLeft: 0,
101
+ spec: null,
102
+ });
103
+ // True between requesting fullscreen and the host applying it, so the
104
+ // collapse-is-back effect below does not fire mid-transition.
105
+ const enteringRef = useRef(false);
106
+
107
+ const selectedId = nav.selectedId;
108
+ // The detail only mounts once the host is actually fullscreen: rendering the
109
+ // tall page inside the small inline frame would flash a cramped layout.
110
+ const showDetail = selectedId != null && mode === "fullscreen";
111
+
112
+ // A host-driven exit from fullscreen (the user used host chrome) means "back".
113
+ useEffect(() => {
114
+ if (mode === "fullscreen") {
115
+ enteringRef.current = false;
116
+ return;
117
+ }
118
+ if (selectedId != null && !enteringRef.current) {
119
+ setNav((prev) => ({ ...prev, selectedId: null, spec: null }));
120
+ }
121
+ }, [mode, selectedId, setNav]);
122
+
123
+ // Restore carousel scroll when back on the carousel. display:none resets
124
+ // scrollLeft, so re-apply once it is visible again (layout effect, not mount).
125
+ useLayoutEffect(() => {
126
+ if (!showDetail && trackRef.current) {
127
+ trackRef.current.scrollLeft = nav.scrollLeft;
128
+ }
129
+ }, [showDetail, nav.scrollLeft]);
130
+
131
+ function openProduct(id: string) {
132
+ enteringRef.current = true;
133
+ const list = responseMetadata?.products ?? [];
134
+ let spec: ProductSpec | null = null;
135
+ for (const product of list) {
136
+ if (product.id === id) {
137
+ spec = buildProductSpec(product);
138
+ break;
139
+ }
140
+ }
141
+ setNav({
142
+ selectedId: id,
143
+ scrollLeft: trackRef.current?.scrollLeft ?? 0,
144
+ spec,
145
+ });
146
+ setMode("fullscreen");
147
+ }
148
+
149
+ // Tool still resolving: reserve the layout with skeleton cards.
150
+ if (responseMetadata == null) {
151
+ const skeletons: ReactNode[] = [];
152
+ for (let i = 0; i < SKELETON_COUNT; i++) {
153
+ skeletons.push(<ProductCardSkeleton key={i} />);
154
+ }
155
+ return (
156
+ <ViewFrame>
157
+ <div className={sprinkles({ p: "3xs" })}>
158
+ <ProductCarousel loading>{skeletons}</ProductCarousel>
159
+ </div>
160
+ </ViewFrame>
161
+ );
162
+ }
163
+
164
+ const products = responseMetadata.products ?? [];
165
+
166
+ if (products.length === 0) {
167
+ return (
168
+ <ViewFrame>
169
+ <EmptyState message={labels.noProducts} />
170
+ </ViewFrame>
171
+ );
172
+ }
173
+
174
+ // Guard against a stale id (e.g. the model rendered a new carousel while a
175
+ // detail was open): fall back to the carousel rather than an empty page.
176
+ const selectedProduct =
177
+ selectedId != null
178
+ ? products.find((product) => product.id === selectedId)
179
+ : undefined;
180
+ // The detail actually renders only when we have a product to show. Everything
181
+ // that hides the carousel keys off this, so a stale id shows the carousel, not
182
+ // a blank page.
183
+ const detailProduct = showDetail ? selectedProduct : undefined;
184
+
185
+ const cards: ReactNode[] = [];
186
+ for (const [index, product] of products.entries()) {
187
+ const { card } = product;
188
+ cards.push(
189
+ <div key={product.id} className={cardStyles.cardClickable}>
190
+ <ProductCard
191
+ // Drop per-card grounding while the detail owns the screen.
192
+ data-llm={
193
+ !detailProduct && visibleIndices.includes(index)
194
+ ? narrate(product, index)
195
+ : ""
196
+ }
197
+ title={card.title}
198
+ price={card.price}
199
+ media={card.media}
200
+ outOfStock={card.outOfStock}
201
+ />
202
+ <button
203
+ type="button"
204
+ aria-label={card.title}
205
+ className={cardStyles.cardButton}
206
+ onClick={() => openProduct(product.id)}
207
+ />
208
+ </div>,
209
+ );
210
+ }
211
+
212
+ const narration = `Carousel of ${products.length} product(s); the user scrolls horizontally. On screen now:`;
213
+
214
+ return (
215
+ <ViewFrame>
216
+ <div
217
+ className={sprinkles({ p: "3xs" })}
218
+ style={{ display: detailProduct ? "none" : undefined }}
219
+ >
220
+ <ProductCarousel
221
+ trackRef={trackRef}
222
+ onVisibleChange={setVisibleIndices}
223
+ data-llm={detailProduct ? "" : narration}
224
+ >
225
+ {cards}
226
+ </ProductCarousel>
227
+ </div>
228
+ {detailProduct ? <DetailView product={detailProduct} /> : null}
229
+ </ViewFrame>
230
+ );
231
+ }
232
+
233
+ export default Carousel;
@@ -0,0 +1,11 @@
1
+ {
2
+ "extends": "skybridge/tsconfig",
3
+
4
+ "compilerOptions": {
5
+ "module": "ESNext",
6
+ "moduleResolution": "Bundler",
7
+ "types": ["node", "vite/client"]
8
+ },
9
+
10
+ "include": ["src", ".skybridge/**/*.d.ts"]
11
+ }
@@ -0,0 +1,8 @@
1
+ import { skybridge } from "@skybridge/vite-plugin";
2
+ import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";
3
+ import react from "@vitejs/plugin-react";
4
+ import { defineConfig, type PluginOption } from "vite";
5
+
6
+ export default defineConfig({
7
+ plugins: [skybridge() as PluginOption, react(), vanillaExtractPlugin()],
8
+ });
@@ -1 +0,0 @@
1
- export {};
@@ -1,33 +0,0 @@
1
- import { randomBytes } from "node:crypto";
2
- import fs from "node:fs/promises";
3
- import path from "node:path";
4
- import { afterEach, beforeEach, describe, expect, it } from "vitest";
5
- import { init } from "./index.js";
6
- describe("create-skybridge", () => {
7
- let tempDirName;
8
- beforeEach(() => {
9
- tempDirName = `test-${randomBytes(2).toString("hex")}`;
10
- });
11
- afterEach(async () => {
12
- await fs.rm(path.join(process.cwd(), tempDirName), {
13
- recursive: true,
14
- force: true,
15
- });
16
- });
17
- it("should copy the template", async () => {
18
- const name = `../../${tempDirName}//project$`;
19
- await init([name]);
20
- await fs.access(path.join(process.cwd(), tempDirName, "project", ".gitignore"));
21
- expect(fs.access(path.join(process.cwd(), tempDirName, "project", ".npmrc"))).rejects.toThrowError();
22
- });
23
- it("should download template from repo", async () => {
24
- const name = `../../${tempDirName}//project$`;
25
- await init([
26
- name,
27
- "--repo",
28
- "github:alpic-ai/skybridge/examples/ecom-carousel",
29
- ]);
30
- await fs.access(path.join(process.cwd(), tempDirName, "project", ".gitignore"));
31
- expect(fs.access(path.join(process.cwd(), tempDirName, "project", ".npmrc"))).rejects.toThrowError();
32
- });
33
- });
@@ -1 +0,0 @@
1
- Before writing code, first explore the project structure, then invoke the chatgpt-app-builder skill for documentation.
@@ -1,97 +0,0 @@
1
- # Skybridge Starter
2
-
3
- A minimal TypeScript template for building MCP and ChatGPT Apps with the [Skybridge](https://docs.skybridge.tech/home) framework.
4
-
5
- ## Getting Started
6
-
7
- ### Prerequisites
8
-
9
- - Node.js 24+
10
- - HTTP tunnel such as [ngrok](https://ngrok.com/download) if you want to test with remote MCP hosts like ChatGPT or Claude.ai.
11
-
12
- ### Local Development
13
-
14
- #### 1. Install
15
-
16
- ```bash
17
- npm install
18
- # or
19
- yarn install
20
- # or
21
- pnpm install
22
- # or
23
- bun install
24
- ```
25
-
26
- #### 2. Start your local server
27
-
28
- Run the development server from the root directory:
29
-
30
- ```bash
31
- npm run dev
32
- # or
33
- yarn dev
34
- # or
35
- pnpm dev
36
- # or
37
- bun dev
38
- ```
39
-
40
- This command starts:
41
- - Your MCP server at `http://localhost:3000/mcp`.
42
- - Skybridge DevTools UI at `http://localhost:3000/`.
43
-
44
- #### 3. Project structure
45
-
46
- ```
47
- ├── server/
48
- │ └── src/
49
- │ └── index.ts # Server entry point
50
- ├── web/
51
- │ ├── src/
52
- │ │ ├── widgets/ # React components (one per widget)
53
- │ │ ├── helpers.ts # Shared utilities
54
- │ │ └── index.css # Global styles
55
- │ └── vite.config.ts
56
- ├── alpic.json # Deployment config
57
- ├── nodemon.json # Dev server config
58
- └── package.json
59
- ```
60
-
61
- ### Create your first widget
62
-
63
- #### 1. Add a new widget
64
-
65
- - 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)
66
- - Create a matching React component at `web/src/widgets/my-widget.tsx`. **The file name must match the widget name exactly**.
67
-
68
- #### 2. Edit widgets with Hot Module Replacement (HMR)
69
-
70
- Edit and save components in `web/src/widgets/` — changes will appear instantly inside your App.
71
-
72
- #### 3. Edit server code
73
-
74
- Modify files in `server/` and refresh the connection with your testing MCP Client to see the changes.
75
-
76
- ### Testing your App
77
-
78
- You can test your App locally by using our DevTools UI on `localhost:3000` while running the `pnpm dev` command.
79
-
80
- 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).
81
-
82
-
83
- ## Deploy to Production
84
-
85
- Skybridge is infrastructure vendor agnostic, and your app can be deployed on any cloud platform supporting MCP.
86
-
87
- The simplest way to deploy your App in minutes is [Alpic](https://alpic.ai/).
88
- 1. Create an account on [Alpic platform](https://app.alpic.ai/).
89
- 2. Connect your GitHub repository to automatically deploy at each commit.
90
- 3. Use your remote App URL to connect it to MCP Clients, or use the Alpic Playground to easily test your App.
91
-
92
- ## Resources
93
- - [Skybridge Documentation](https://docs.skybridge.tech/)
94
- - [Apps SDK Documentation](https://developers.openai.com/apps-sdk)
95
- - [MCP Apps Documentation](https://github.com/modelcontextprotocol/ext-apps/tree/main)
96
- - [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
97
- - [Alpic Documentation](https://docs.alpic.ai/)
@@ -1,21 +0,0 @@
1
- #!/bin/sh
2
- basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
3
-
4
- case `uname` in
5
- *CYGWIN*|*MINGW*|*MSYS*)
6
- if command -v cygpath > /dev/null 2>&1; then
7
- basedir=`cygpath -w "$basedir"`
8
- fi
9
- ;;
10
- esac
11
-
12
- if [ -z "$NODE_PATH" ]; then
13
- export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.93.6_@opentelemetry+api@1.9.0_arktype@2.1.27_rxjs@7.8.2_typescript@5.9.3/node_modules/alpic/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.93.6_@opentelemetry+api@1.9.0_arktype@2.1.27_rxjs@7.8.2_typescript@5.9.3/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
14
- else
15
- export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.93.6_@opentelemetry+api@1.9.0_arktype@2.1.27_rxjs@7.8.2_typescript@5.9.3/node_modules/alpic/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.93.6_@opentelemetry+api@1.9.0_arktype@2.1.27_rxjs@7.8.2_typescript@5.9.3/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
16
- fi
17
- if [ -x "$basedir/node" ]; then
18
- exec "$basedir/node" "$basedir/../alpic/bin/run.js" "$@"
19
- else
20
- exec node "$basedir/../alpic/bin/run.js" "$@"
21
- fi
@@ -1,21 +0,0 @@
1
- #!/bin/sh
2
- basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
3
-
4
- case `uname` in
5
- *CYGWIN*|*MINGW*|*MSYS*)
6
- if command -v cygpath > /dev/null 2>&1; then
7
- basedir=`cygpath -w "$basedir"`
8
- fi
9
- ;;
10
- esac
11
-
12
- if [ -z "$NODE_PATH" ]; then
13
- export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.33.4_@modelcontextprotocol+sdk@1.27.1_zod@4.3.6__@skybridge+devtools@0.33.4_fe9b96aa1b19c7f7fe4b0d71e9df0789/node_modules/skybridge/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.33.4_@modelcontextprotocol+sdk@1.27.1_zod@4.3.6__@skybridge+devtools@0.33.4_fe9b96aa1b19c7f7fe4b0d71e9df0789/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
14
- else
15
- export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.33.4_@modelcontextprotocol+sdk@1.27.1_zod@4.3.6__@skybridge+devtools@0.33.4_fe9b96aa1b19c7f7fe4b0d71e9df0789/node_modules/skybridge/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.33.4_@modelcontextprotocol+sdk@1.27.1_zod@4.3.6__@skybridge+devtools@0.33.4_fe9b96aa1b19c7f7fe4b0d71e9df0789/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
16
- fi
17
- if [ -x "$basedir/node" ]; then
18
- exec "$basedir/node" "$basedir/../skybridge/bin/run.js" "$@"
19
- else
20
- exec node "$basedir/../skybridge/bin/run.js" "$@"
21
- fi