create-skybridge 0.0.0-dev.e159727 → 0.0.0-dev.e17f86d

package/dist/index.test.js

@@ -18,6 +18,8 @@ describe("create-skybridge", () => {
         const name = `../../${tempDirName}//project$`;
         await init([name]);
         await fs.access(path.join(process.cwd(), tempDirName, "project", ".gitignore"));
+        await fs.access(path.join(process.cwd(), tempDirName, "project", ".dockerignore"));
+        await fs.access(path.join(process.cwd(), tempDirName, "project", "Dockerfile"));
         expect(fs.access(path.join(process.cwd(), tempDirName, "project", ".npmrc"))).rejects.toThrowError();
     });
     it("should download template from repo", { timeout: 10000 }, async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-skybridge",
-  "version": "0.0.0-dev.e159727",
+  "version": "0.0.0-dev.e17f86d",
   "type": "module",
   "license": "MIT",
   "author": "Alpic",

package/template/.dockerignore

@@ -0,0 +1,4 @@
+node_modules
+.git
+dist
+.env*

package/template/Dockerfile

@@ -0,0 +1,53 @@
+# syntax=docker/dockerfile:1
+
+# Dockerfile for a Skybridge MCP server.
+#
+# Detects npm, yarn, or pnpm from the lockfile in your project.
+# (For bun or deno, adapt the install/build/prune commands below.)
+
+# Build stage: install deps, compile the app, then prune dev deps.
+FROM node:24-slim AS build
+WORKDIR /app
+
+COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./
+RUN --mount=type=cache,target=/root/.npm \
+    --mount=type=cache,target=/usr/local/share/.cache/yarn \
+    --mount=type=cache,target=/root/.local/share/pnpm/store \
+    if [ -f package-lock.json ]; then \
+      npm ci; \
+    elif [ -f yarn.lock ]; then \
+      corepack enable yarn && yarn install --frozen-lockfile; \
+    elif [ -f pnpm-lock.yaml ]; then \
+      corepack enable pnpm && pnpm install --frozen-lockfile; \
+    else \
+      echo "No lockfile found." && exit 1; \
+    fi
+
+ENV NODE_ENV=production
+
+COPY . .
+RUN if [ -f package-lock.json ]; then \
+      npm run build && npm prune --omit=dev; \
+    elif [ -f yarn.lock ]; then \
+      corepack enable yarn && yarn build && yarn install --frozen-lockfile --production=true; \
+    elif [ -f pnpm-lock.yaml ]; then \
+      corepack enable pnpm && pnpm build && pnpm prune --prod; \
+    fi
+
+# Runtime stage: copy built artifacts and prod deps, run as non-root.
+FROM node:24-slim AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+
+USER node
+
+COPY --from=build --chown=node:node /app/node_modules ./node_modules
+COPY --from=build --chown=node:node /app/dist ./dist
+COPY --from=build --chown=node:node /app/package.json ./package.json
+
+EXPOSE 3000
+
+# Run the built server directly rather than via `npm start` / `skybridge start`.
+# Each wrapper adds a process layer that can swallow SIGTERM, which makes
+# graceful shutdowns time out on platforms like Cloud Run, Fly, and k8s.
+CMD ["node", "dist/server.js"]

package/template/package.json

@@ -12,20 +12,26 @@
     "deploy": "alpic deploy"
   },
   "dependencies": {
+    "@alpic-ai/ui": "^1.122.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "lucide-react": "^1.14.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "skybridge": ">=0.0.0-dev.e159727",
+    "skybridge": ">=0.0.0-dev.e17f86d",
+    "sonner": "^2.0.7",
+    "tw-animate-css": "^1.4.0",
     "vite": "^8.0.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@skybridge/devtools": ">=0.35.14 <1.0.0",
+    "@tailwindcss/vite": "^4.2.4",
     "@types/node": "^24.12.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
     "alpic": "^1.104.1",
+    "tailwindcss": "^4.2.4",
     "tsx": "^4.21.0",
     "typescript": "^6.0.2"
   },

package/template/src/index.css

@@ -1,50 +1,35 @@
-@import url("https://fonts.googleapis.com/css2?family=Playfair+Display:ital,wght@1,600&display=swap");
+@import url("https://fonts.googleapis.com/css2?family=Mozilla+Text:wght@400..700&display=swap");
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "@alpic-ai/ui/theme";
 
-.container {
-  display: flex;
-  justify-content: center;
-  align-items: center;
-  min-height: 100%;
-  padding: 1rem;
-  box-sizing: border-box;
+@source "../node_modules/@alpic-ai/ui/src";
+
+@theme {
+  --font-mozilla: "Mozilla Text", serif;
+  --animate-float: float 3s ease-in-out infinite;
+  --animate-twirl: twirl 20s ease-in-out infinite;
+  --animate-aurora: aurora 20s ease-in-out infinite;
+  --animate-gradient-flow: gradient-flow 6s linear infinite;
 }
 
-.ball {
-  background: radial-gradient(
-    circle at 30% 30%,
-    #454565 0%,
-    #1c1c30 40%,
-    #0a0a10 100%
-  );
-  border-radius: 50%;
-  width: 12rem;
-  height: 12rem;
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  font-family: monospace;
-  text-align: center;
-  position: relative;
-  box-shadow:
-    0 10px 30px rgba(0, 0, 0, 0.5),
-    0 5px 15px rgba(0, 0, 0, 0.3),
-    inset 0 -20px 40px rgba(0, 0, 0, 0.6);
-  animation:
-    float 3s ease-in-out infinite,
-    colorShift 15s ease-in-out infinite;
-  transition: transform 0.3s ease;
-  cursor: pointer;
-  border: 1px solid rgba(30, 30, 50, 0.6);
+@keyframes gradient-flow {
+  0% {
+    background-position: 200% 50%;
+  }
+  100% {
+    background-position: 0% 50%;
+  }
 }
 
-.ball:hover {
-  transform: scale(1.05) translateY(-8px);
-  animation: colorShift 15s ease-in-out infinite;
-  box-shadow:
-    0 20px 50px rgba(0, 0, 0, 0.6),
-    0 10px 25px rgba(0, 0, 0, 0.4),
-    inset 0 -20px 40px rgba(0, 0, 0, 0.6);
+@keyframes aurora {
+  0%,
+  100% {
+    background-position: 0% 50%;
+  }
+  50% {
+    background-position: 100% 50%;
+  }
 }
 
 @keyframes float {
@@ -53,100 +38,22 @@
     transform: translateY(0);
   }
   50% {
-    transform: translateY(-8px);
+    transform: translateY(-6px);
   }
 }
 
-@keyframes colorShift {
+@keyframes twirl {
   0%,
-  100% {
-    background: radial-gradient(
-      circle at 30% 30%,
-      #454565 0%,
-      #1c1c30 40%,
-      #0a0a10 100%
-    );
+  80% {
+    transform: rotateY(0deg);
   }
-  25% {
-    background: radial-gradient(
-      circle at 30% 30%,
-      #3f4a65 0%,
-      #181e30 40%,
-      #090a10 100%
-    );
+  85% {
+    transform: rotateY(180deg);
   }
-  50% {
-    background: radial-gradient(
-      circle at 30% 30%,
-      #3a5065 0%,
-      #152230 40%,
-      #080a10 100%
-    );
+  95% {
+    transform: rotateY(180deg);
   }
-  75% {
-    background: radial-gradient(
-      circle at 30% 30%,
-      #3f4a65 0%,
-      #181e30 40%,
-      #090a10 100%
-    );
+  100% {
+    transform: rotateY(360deg);
   }
 }
-
-.ball::before {
-  content: "";
-  position: absolute;
-  top: 8%;
-  left: 20%;
-  width: 30%;
-  height: 20%;
-  background: radial-gradient(
-    ellipse,
-    rgba(255, 255, 255, 0.3) 0%,
-    transparent 70%
-  );
-  border-radius: 50%;
-  pointer-events: none;
-}
-
-.ball::after {
-  content: "";
-  position: absolute;
-  bottom: 8%;
-  right: 25%;
-  width: 25%;
-  height: 10%;
-  background: radial-gradient(
-    ellipse,
-    rgba(255, 255, 255, 0.1) 0%,
-    transparent 70%
-  );
-  border-radius: 50%;
-  pointer-events: none;
-}
-
-.question {
-  font-size: clamp(0.5rem, 2vw, 0.75rem);
-  color: lightgrey;
-  max-width: 90%;
-  word-wrap: break-word;
-  overflow-wrap: break-word;
-  text-align: center;
-  line-height: 1.3;
-  font-style: italic;
-}
-
-.answer {
-  font-family: "Playfair Display", serif;
-  font-style: italic;
-  font-size: 1.25rem;
-  font-weight: 600;
-  margin-top: 0.5rem;
-  color: #7dd3fc;
-  text-shadow: 0 0 10px rgba(125, 211, 252, 0.5);
-  max-width: 90%;
-  word-wrap: break-word;
-  overflow-wrap: break-word;
-  text-align: center;
-  line-height: 1.3;
-}

package/template/src/server.ts

@@ -1,61 +1,77 @@
 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: {} },
-).registerTool(
-  {
-    name: "magic-8-ball",
-    description: "For fortune-telling or seeking advice.",
-    inputSchema: {
-      question: z.string().describe("The user question."),
-    },
-    view: {
-      component: "magic-8-ball",
-      description: "Magic 8 Ball",
+)
+  .registerTool(
+    {
+      name: "start",
+      description: "Onboard Skybridge",
+      inputSchema: {
+        name: z.string().optional().describe("The user name."),
+      },
+      view: {
+        component: "onboarding",
+        description: "Onboarding deck",
+        csp: {
+          resourceDomains: [
+            "https://fonts.googleapis.com",
+            "https://fonts.gstatic.com",
+          ],
+          redirectDomains: ["https://docs.skybridge.tech"],
+        },
+      },
     },
-  },
-  async ({ question }) => {
-    try {
-      const hash = question
-        .split("")
-        .reduce((acc, char) => acc + char.charCodeAt(0), 0);
-      const answer = Answers[hash % Answers.length];
+    async ({ name }) => {
       return {
-        structuredContent: { answer },
+        structuredContent: { name },
+        content: [{ type: "text", text: `User name: ${name}` }],
         isError: false,
       };
-    } catch (error) {
+    },
+  )
+  .registerTool(
+    {
+      name: "get-fortune-cookie",
+      description: "Get fortune cookie",
+    },
+    async () => {
+      const predictions = [
+        "A pleasant surprise is waiting for you.",
+        "Your hard work will soon pay off.",
+        "An unexpected friendship will brighten your week.",
+        "The best is yet to come.",
+        "A small step today leads to a giant leap tomorrow.",
+        "Trust your instincts: they are sharper than you think.",
+        "Adventure awaits just around the corner.",
+        "A long-forgotten idea will return with great success.",
+        "Kindness given today will be returned threefold.",
+        "Something you lost will soon be found.",
+      ];
+      const prediction =
+        predictions[Math.floor(Math.random() * predictions.length)];
+
+      // simulate backend work
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+
       return {
-        content: [{ type: "text", text: `Error: ${error}` }],
-        isError: true,
+        structuredContent: { prediction },
+        content: [{ type: "text", text: prediction }],
+        isError: false,
       };
-    }
-  },
-);
+    },
+  );
+
+if (process.env.NODE_ENV === "production") {
+  const { default: manifest } = await import("./vite-manifest.js");
+  server.setViteManifest(manifest);
+}
 
-server.run();
+export default await server.run();
 
 export type AppType = typeof server;

package/template/src/views/components/doc-link.tsx

@@ -0,0 +1,22 @@
+import type { ReactNode } from "react";
+import { useOpenExternal } from "skybridge/web";
+
+export default function DocLink({
+  href,
+  children,
+}: {
+  href: string;
+  children: ReactNode;
+}) {
+  // useOpenExternal: open a URL in a new browser tab from inside the iframe.
+  const openExternal = useOpenExternal();
+  return (
+    <button
+      type="button"
+      onClick={() => openExternal(href)}
+      className="underline underline-offset-4"
+    >
+      {children}
+    </button>
+  );
+}

package/template/src/views/components/doc.tsx

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+
+export default function Doc({ children }: { children: ReactNode }) {
+  return (
+    <p className="flex items-start gap-2 type-text-xs text-muted-foreground mt-auto">
+      <svg
+        viewBox="0 0 90 90"
+        xmlns="http://www.w3.org/2000/svg"
+        role="img"
+        aria-label="Skybridge"
+        className="size-4 shrink-0 mt-0.5"
+      >
+        <path
+          d="M17.2704 89.9987C37.5976 24.3967 65.182 12.9084 89.9996 35.3807V84.1606C89.9996 87.3849 87.3858 89.9987 84.1615 89.9987H17.2704ZM84.1615 0C87.3858 0 89.9996 2.6139 89.9996 5.83819V30.9146C52.0566 -5.26767 14.9006 31.2366 0.000976562 57.6768V5.83819C0.00104114 2.6139 2.61486 2.23904e-08 5.83917 0H84.1615Z"
+          fill="currentColor"
+        />
+      </svg>
+      <span>{children}</span>
+    </p>
+  );
+}

package/template/src/views/components/nav.tsx

@@ -0,0 +1,31 @@
+import { Button } from "@alpic-ai/ui/components/button";
+import { CheckCheck } from "lucide-react";
+
+export default function Nav({
+  current,
+  total,
+  onChange,
+}: {
+  current: number;
+  total: number;
+  onChange: (index: number) => void;
+}) {
+  return (
+    <div className="flex justify-end gap-2 mt-auto">
+      <Button
+        variant="secondary"
+        disabled={current === 0}
+        onClick={() => onChange(Math.max(current - 1, 0))}
+      >
+        Previous
+      </Button>
+      <Button
+        disabled={current === total - 1}
+        onClick={() => onChange(Math.min(current + 1, total - 1))}
+      >
+        <CheckCheck />
+        Next
+      </Button>
+    </div>
+  );
+}

package/template/src/views/components/progress.tsx

@@ -0,0 +1,35 @@
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@alpic-ai/ui/components/tooltip";
+
+export default function Progress({
+  steps,
+  current,
+  onSelect,
+}: {
+  steps: readonly string[];
+  current: number;
+  onSelect: (index: number) => void;
+}) {
+  return (
+    <div className="flex gap-1.5">
+      {steps.map((label, i) => (
+        <Tooltip key={label}>
+          <TooltipTrigger asChild>
+            <button
+              type="button"
+              onClick={() => onSelect(i)}
+              className={`relative h-1 flex-1 rounded-full transition-opacity before:absolute before:-inset-y-5 before:inset-x-0 before:content-[''] [@media(hover:hover)]:hover:opacity-70 ${
+                i <= current ? "bg-primary" : "bg-muted"
+              }`}
+              aria-label={label}
+            />
+          </TooltipTrigger>
+          <TooltipContent>{label}</TooltipContent>
+        </Tooltip>
+      ))}
+    </div>
+  );
+}

package/template/src/views/components/steps/outro.tsx

@@ -0,0 +1,68 @@
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardTitle,
+} from "@alpic-ai/ui/components/card";
+import { BookOpen, CircleStar } from "lucide-react";
+import { useOpenExternal } from "skybridge/web";
+
+const LINKS = [
+  {
+    icon: CircleStar,
+    title: "See the examples",
+    description:
+      "Templates for OAuth, e-commerce, dashboards, games, and many more.",
+    href: "https://docs.skybridge.tech/showcase#examples",
+  },
+  {
+    icon: BookOpen,
+    title: "Read the docs",
+    description: "Learn more about Skybridge concepts, API, and tooling.",
+    href: "https://docs.skybridge.tech",
+  },
+];
+
+export default function Outro() {
+  // useOpenExternal: open a URL in a new browser tab from inside the iframe.
+  const openExternal = useOpenExternal();
+
+  return (
+    <>
+      <div className="flex flex-1 flex-col justify-center gap-3">
+        <h1 className="type-display-xs font-mozilla font-semibold text-primary">
+          That's a wrap!
+        </h1>
+        <p>
+          You've just mastered how{" "}
+          <strong>
+            the data flows between the tools, the view, and the model
+          </strong>
+          . You can start{" "}
+          <span className="bg-gradient-to-r from-primary via-cyan-500 to-primary bg-[length:200%_100%] bg-clip-text text-transparent font-semibold animate-gradient-flow">
+            vibing
+          </span>{" "}
+          now from this very template or:
+        </p>
+      </div>
+      <div className="grid grid-cols-2 gap-3 mt-auto">
+        {LINKS.map(({ icon: Icon, title, description, href }) => (
+          <Card
+            key={title}
+            hoverable
+            className="cursor-pointer bg-white/50 dark:bg-zinc-900/50"
+            onClick={() => openExternal(href)}
+          >
+            <CardContent className="flex flex-col gap-2">
+              <div className="flex items-center gap-3">
+                <Icon className="size-5 shrink-0 text-primary" />
+                <CardTitle>{title}</CardTitle>
+              </div>
+              <CardDescription>{description}</CardDescription>
+            </CardContent>
+          </Card>
+        ))}
+      </div>
+    </>
+  );
+}

package/template/src/views/components/steps/state.tsx

@@ -0,0 +1,47 @@
+import { Button } from "@alpic-ai/ui/components/button";
+import { HatGlasses } from "lucide-react";
+import Doc from "@/views/components/doc.js";
+import DocLink from "@/views/components/doc-link.js";
+import { useMascot } from "@/views/use-mascot.js";
+
+export default function State() {
+  const { hat, changeHat } = useMascot();
+
+  return (
+    <>
+      <div className="flex flex-1 flex-col justify-center gap-3">
+        <p>
+          The <strong>view state</strong> can be shared with the model:
+        </p>
+        <div className="flex">
+          <Button variant="cta" onClick={changeHat}>
+            <HatGlasses />
+            Change my hat
+          </Button>
+        </div>
+        <p className={`mt-2 ${hat ? "" : "invisible"}`} aria-hidden={!hat}>
+          Now, the LLM also knows I'm wearing a glorious{" "}
+          <span
+            // data-llm: describe what the user views to the model so they can collaborate
+            data-llm={`Mascot is wearing ${hat}`}
+            className="text-primary font-mozilla"
+          >
+            {hat}
+          </span>
+          .
+        </p>
+      </div>
+      <Doc>
+        Use{" "}
+        <DocLink href="https://docs.skybridge.tech/api-reference/use-view-state">
+          useViewState
+        </DocLink>{" "}
+        to update the context and{" "}
+        <DocLink href="https://docs.skybridge.tech/api-reference/data-llm">
+          data-llm
+        </DocLink>{" "}
+        to describe the UI.
+      </Doc>
+    </>
+  );
+}

package/template/src/views/components/steps/tool-call.tsx

@@ -0,0 +1,53 @@
+import { Button } from "@alpic-ai/ui/components/button";
+import { Cookie } from "lucide-react";
+import { useEffect, useState } from "react";
+import { useCallTool } from "@/helpers.js";
+import Doc from "@/views/components/doc.js";
+import DocLink from "@/views/components/doc-link.js";
+
+export default function ToolCall() {
+  // useCallTool: invoke a server tool from within the view.
+  const { callTool, isPending, data } = useCallTool("get-fortune-cookie");
+  const [prediction, setPrediction] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (data) {
+      setPrediction(data.structuredContent.prediction);
+    }
+  }, [data]);
+
+  return (
+    <>
+      <div className="flex flex-1 flex-col justify-center gap-3">
+        <p className="">
+          <strong>Tools</strong> can also be triggered from the view:
+        </p>
+        <div className="flex">
+          <Button
+            variant="cta"
+            loading={isPending}
+            icon={<Cookie />}
+            onClick={() => callTool()}
+          >
+            <code>get-fortune-cookie</code>
+          </Button>
+        </div>
+        <p
+          className={`font-mozilla italic text-primary mt-2 ${
+            prediction ? "" : "invisible"
+          }`}
+          aria-hidden={!prediction}
+        >
+          {prediction || "none"}
+        </p>
+      </div>
+      <Doc>
+        Use{" "}
+        <DocLink href="https://docs.skybridge.tech/api-reference/use-call-tool">
+          useCallTool
+        </DocLink>{" "}
+        to request tools from within the view.
+      </Doc>
+    </>
+  );
+}

package/template/src/views/components/steps/tool-output.tsx

@@ -0,0 +1,40 @@
+import { useToolInfo } from "@/helpers.js";
+import Doc from "@/views/components/doc.js";
+import DocLink from "@/views/components/doc-link.js";
+
+export default function ToolOutput() {
+  // useToolInfo: read the input, output and metadata of the tool that opened this view.
+  const { output } = useToolInfo<"start">();
+  const name = output?.name;
+
+  return (
+    <>
+      <div className="flex flex-1 flex-col justify-center gap-3">
+        <h1 className="type-display-xs font-mozilla font-semibold">
+          Greetings,{" "}
+          <span className="text-primary">{name ?? "stranger"} !</span>
+        </h1>
+        {name ? (
+          <p>
+            You're wondering how do I know your name, don't you? Well, it's
+            because the view reads the <strong>tool output</strong>. The LLM
+            knows about it too.
+          </p>
+        ) : (
+          <p>
+            The view reads the <strong>tool output</strong>, but no{" "}
+            <code>name</code> was passed this time. Try again with you surname
+            to see with this view personalize.
+          </p>
+        )}
+      </div>
+      <Doc>
+        Use{" "}
+        <DocLink href="https://docs.skybridge.tech/api-reference/use-tool-info">
+          useToolInfo
+        </DocLink>{" "}
+        to hydrates the view with tool input, output and metadata.
+      </Doc>
+    </>
+  );
+}

package/template/src/views/onboarding.tsx

@@ -0,0 +1,63 @@
+import "@/index.css";
+
+import { useState } from "react";
+import { useLayout } from "skybridge/web";
+import Nav from "./components/nav.js";
+import Progress from "./components/progress.js";
+import Outro from "./components/steps/outro.js";
+import State from "./components/steps/state.js";
+import ToolCall from "./components/steps/tool-call.js";
+import ToolOutput from "./components/steps/tool-output.js";
+import { useMascot } from "./use-mascot.js";
+
+const STEPS = [
+  { label: "Reading tool output", Component: ToolOutput },
+  { label: "Sharing view state", Component: State },
+  { label: "Calling tools", Component: ToolCall },
+  { label: "Examples & docs", Component: Outro },
+] as const;
+
+export default function Onboarding() {
+  // useLayout: read host layout info (theme, display mode, locale, ...).
+  const { theme } = useLayout();
+
+  const [step, setStep] = useState(0);
+  const { img } = useMascot();
+
+  return (
+    <div
+      className={`${theme === "dark" ? "dark" : ""} mx-auto w-full max-w-4xl rounded-xl border border-border overflow-hidden bg-background text-foreground`}
+    >
+      <div className="min-h-[34rem] md:min-h-95 flex flex-col items-center gap-6 p-6 bg-gradient-to-br from-purple-50 via-white to-cyan-50 dark:from-purple-950/30 dark:via-zinc-950 dark:to-cyan-900/30 bg-[length:200%_200%] animate-aurora md:flex-row md:items-stretch">
+        <div className="shrink-0 self-center animate-float">
+          <img
+            src={img}
+            alt="Skybridge mascot"
+            className="h-32 w-32 md:h-50 md:w-50 object-contain animate-twirl"
+          />
+        </div>
+        <div className="flex w-full flex-1 flex-col gap-6">
+          <Progress
+            steps={STEPS.map(({ label }) => label)}
+            current={step}
+            onSelect={setStep}
+          />
+          <div className="grid flex-1">
+            {STEPS.map(({ label, Component }, i) => (
+              <div
+                key={label}
+                className={`col-start-1 row-start-1 flex flex-col gap-6 ${
+                  step === i ? "" : "invisible pointer-events-none"
+                }`}
+                aria-hidden={step !== i}
+              >
+                <Component />
+              </div>
+            ))}
+          </div>
+          <Nav current={step} total={STEPS.length} onChange={setStep} />
+        </div>
+      </div>
+    </div>
+  );
+}

package/template/src/views/use-mascot.ts

@@ -0,0 +1,60 @@
+import { useEffect } from "react";
+import { useViewState } from "skybridge/web";
+import beret from "./images/mascot/beret.png";
+import chapka from "./images/mascot/chapka.png";
+import cowboyHat from "./images/mascot/cowboy-hat.png";
+import fez from "./images/mascot/fez.png";
+import jesterHat from "./images/mascot/jester-hat.png";
+import mitre from "./images/mascot/mitre.png";
+import nonLa from "./images/mascot/non-la.png";
+import original from "./images/mascot/original.png";
+import propellerBeanie from "./images/mascot/propeller-beanie.png";
+import skiMask from "./images/mascot/ski-mask.png";
+import sombrero from "./images/mascot/sombrero.png";
+import topHat from "./images/mascot/top-hat.png";
+import vikingHelmet from "./images/mascot/viking-helmet.png";
+
+const Hats = {
+  beret,
+  chapka,
+  "cowboy hat": cowboyHat,
+  fez,
+  "jester hat": jesterHat,
+  mitre,
+  "nón lá": nonLa,
+  "propeller beanie": propellerBeanie,
+  "ski mask": skiMask,
+  sombrero,
+  "top hat": topHat,
+  "viking helmet": vikingHelmet,
+} as const;
+
+type HatLabel = keyof typeof Hats;
+
+const LABELS = Object.keys(Hats) as HatLabel[];
+
+export function useMascot() {
+  // useViewState: persist UI state on the host and surface it to the model.
+  const [state, setState] = useViewState<{ hat?: HatLabel }>({});
+  const { hat } = state;
+  const img = hat ? Hats[hat] : original;
+
+  // Preload all hats once so swaps are instant.
+  useEffect(() => {
+    for (const src of Object.values(Hats)) {
+      new Image().src = src;
+    }
+  }, []);
+
+  return {
+    img,
+    hat,
+    changeHat: () => {
+      setState((prev) => {
+        const others = LABELS.filter((l) => l !== prev.hat);
+        const next = others[Math.floor(Math.random() * others.length)];
+        return { ...prev, hat: next };
+      });
+    },
+  };
+}

package/template/src/vite-manifest.d.ts

@@ -0,0 +1,4 @@
+// Typed shim for the Vite manifest emitted by `skybridge build`. The actual
+// `vite-manifest.js` is generated alongside this file and gitignored.
+declare const manifest: Record<string, { file: string }>;
+export default manifest;

package/template/vite.config.ts

@@ -1,10 +1,11 @@
 import path from "node:path";
+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()],
+  plugins: [skybridge(), react(), tailwindcss()],
   resolve: {
     alias: {
       "@": path.resolve(__dirname, "./src"),

package/template/src/components/ball.tsx

@@ -1,22 +0,0 @@
-export function Ball({
-  question,
-  answer,
-}: {
-  question?: string;
-  answer?: string;
-}) {
-  return (
-    <div className="container">
-      <div className="ball">
-        {answer ? (
-          <>
-            <div className="question">{question}</div>
-            <div className="answer">{answer}</div>
-          </>
-        ) : (
-          <div className="question">Shaking...</div>
-        )}
-      </div>
-    </div>
-  );
-}

package/template/src/views/magic-8-ball.tsx

@@ -1,10 +0,0 @@
-import "@/index.css";
-
-import { Ball } from "../components/ball.js";
-import { useToolInfo } from "../helpers.js";
-
-export default function Magic8Ball() {
-  const { input, output } = useToolInfo<"magic-8-ball">();
-
-  return <Ball question={input?.question} answer={output?.answer} />;
-}