From ab97e0857c2fbcdf9308e6f9c16d8f8754d03acc Mon Sep 17 00:00:00 2001
From: chaewon-huh <cw.huh@postech.ac.kr>
Date: Mon, 24 Nov 2025 00:10:11 +0900
Subject: [PATCH 1/9] feat(cli): add @openai/apps-sdk-ui dependency to template
 creation

- Add Apps SDK UI as dependency for list, carousel, and albums templates
- Maintain existing template-specific dependencies (lucide-react,
  embla-carousel)
- Keep default template minimal without additional dependencies
- Prepare templates for migration to OpenAI's design system
---
 fastapps/cli/commands/create.py | 221 +++++++++++++++-----------------
 1 file changed, 100 insertions(+), 121 deletions(-)

diff --git a/fastapps/cli/commands/create.py b/fastapps/cli/commands/create.py
index 875a109..bce4731 100644
--- a/fastapps/cli/commands/create.py
+++ b/fastapps/cli/commands/create.py
@@ -121,129 +121,108 @@ def create_widget(name: str, auth_type: str = None, scopes: list = None, templat
                 dest_dir = widget_dir / item.name
                 shutil.copytree(item, dest_dir, dirs_exist_ok=True)
 
-    # Install additional dependencies for templates
-    if template in ["list", "carousel", "albums"]:
-        console.print(f"\n[green][OK] Widget '{name}' created from '{template}' template![/green]")
-
-        dep_name = {"list": "Tailwind CSS", "carousel": "Carousel", "albums": "Albums"}.get(template, "Template")
-        console.print(f"\n[cyan]Installing {dep_name} dependencies...[/cyan]")
-
-        # Check if package.json exists
-        package_json_path = Path("package.json")
-        if package_json_path.exists():
-            try:
-                # Read current package.json
-                with open(package_json_path, 'r') as f:
-                    package_data = json.load(f)
-
-                # Add Tailwind dependencies to devDependencies
-                if 'devDependencies' not in package_data:
-                    package_data['devDependencies'] = {}
-                if 'dependencies' not in package_data:
-                    package_data['dependencies'] = {}
-
-                # Template-specific dependencies
-                if template == "list":
-                    # Dev dependencies for list
-                    template_dev_deps = {
-                        "@tailwindcss/vite": "^4.1.11",
-                        "autoprefixer": "^10.4.21",
-                        "postcss": "^8.5.6",
-                        "tailwindcss": "^4.1.11"
-                    }
-                    # Runtime dependencies for list
-                    template_deps = {
-                        "lucide-react": "^0.552.0"
-                    }
-                elif template == "carousel":
-                    # Dev dependencies for carousel
-                    template_dev_deps = {
-                        "@tailwindcss/vite": "^4.1.11",
-                        "autoprefixer": "^10.4.21",
-                        "postcss": "^8.5.6",
-                        "tailwindcss": "^4.1.11"
-                    }
-                    # Runtime dependencies for carousel
-                    template_deps = {
-                        "lucide-react": "^0.552.0",
-                        "embla-carousel-react": "^8.6.0"
-                    }
-                elif template == "albums":
-                    # Dev dependencies for albums
-                    template_dev_deps = {
-                        "@tailwindcss/vite": "^4.1.11",
-                        "autoprefixer": "^10.4.21",
-                        "postcss": "^8.5.6",
-                        "tailwindcss": "^4.1.11"
-                    }
-                    # Runtime dependencies for albums
-                    template_deps = {
-                        "lucide-react": "^0.552.0",
-                        "embla-carousel-react": "^8.6.0"
-                    }
-                else:
-                    template_dev_deps = {}
-                    template_deps = {}
-
-                # Check if dependencies already exist
-                deps_to_install = []
-                for dep, version in template_dev_deps.items():
-                    if dep not in package_data['devDependencies']:
-                        package_data['devDependencies'][dep] = version
-                        deps_to_install.append(dep)
-
-                for dep, version in template_deps.items():
-                    if dep not in package_data['dependencies']:
-                        package_data['dependencies'][dep] = version
-                        deps_to_install.append(dep)
-
-                # Write updated package.json
-                if deps_to_install:
-                    with open(package_json_path, 'w') as f:
-                        json.dump(package_data, f, indent=2)
-
-                    dep_type = "template" if template else "Tailwind"
-                    console.print(f"[cyan]Added {len(deps_to_install)} {dep_type} dependencies to package.json[/cyan]")
-
-                    # Run npm install
-                    console.print("[cyan]Running npm install...[/cyan]")
-                    try:
-                        result = subprocess.run(
-                            ["npm", "install"],
-                            capture_output=True,
-                            text=True,
-                            check=True
-                        )
-                        success_msg = f"{dep_name} dependencies" if template in ["list", "carousel", "albums"] else "Dependencies"
-                        console.print(f"[green]✓ {success_msg} installed[/green]")
-                    except subprocess.CalledProcessError as e:
-                        console.print("[yellow]⚠ npm install failed. Run 'npm install' manually[/yellow]")
-                    except FileNotFoundError:
-                        console.print("[yellow]⚠ npm not found. Run 'npm install' manually[/yellow]")
-                else:
-                    success_msg = f"{dep_name} dependencies" if template in ["list", "carousel", "albums"] else "Dependencies"
-                    console.print(f"[green]✓ {success_msg} already installed[/green]")
-
-            except Exception as e:
-                console.print(f"[yellow]⚠ Could not update package.json: {e}[/yellow]")
-                if template in ["carousel", "albums"]:
-                    console.print(f"[yellow]Please install {template} dependencies manually:[/yellow]")
-                    console.print("[dim]  npm install embla-carousel-react lucide-react[/dim]")
-                    console.print("[dim]  npm install -D @tailwindcss/vite tailwindcss autoprefixer postcss[/dim]")
-                else:
-                    console.print("[yellow]Please install Tailwind CSS manually:[/yellow]")
-                    console.print("[dim]  npm install -D @tailwindcss/vite tailwindcss autoprefixer postcss[/dim]")
-        else:
-            console.print("[yellow]⚠ package.json not found[/yellow]")
-            if template in ["carousel", "albums"]:
-                console.print(f"[yellow]Please install {template} dependencies manually:[/yellow]")
-                console.print("[dim]  npm install embla-carousel-react lucide-react[/dim]")
-                console.print("[dim]  npm install -D @tailwindcss/vite tailwindcss autoprefixer postcss[/dim]")
+    # Install dependencies for templates (Apps SDK UI + Tailwind + template extras)
+    console.print(f"\n[green][OK] Widget '{name}' created from '{template_name}' template![/green]")
+
+    dep_name = {"list": "List", "carousel": "Carousel", "albums": "Albums"}.get(template_name, "Widget")
+    console.print(f"\n[cyan]Installing {dep_name} dependencies...[/cyan]")
+
+    # Check if package.json exists
+    package_json_path = Path("package.json")
+    if package_json_path.exists():
+        try:
+            # Read current package.json
+            with open(package_json_path, 'r') as f:
+                package_data = json.load(f)
+
+            if 'devDependencies' not in package_data:
+                package_data['devDependencies'] = {}
+            if 'dependencies' not in package_data:
+                package_data['dependencies'] = {}
+
+            # Base deps shared across templates (Apps SDK UI + Tailwind 4)
+            template_dev_deps = {
+                "@tailwindcss/vite": "^4.1.11",
+                "autoprefixer": "^10.4.21",
+                "postcss": "^8.5.6",
+                "tailwindcss": "^4.1.11"
+            }
+            template_deps = {
+                "@openai/apps-sdk-ui": "^0.1.0"
+            }
+
+            # Template-specific runtime deps
+            if template_name == "list":
+                template_deps.update({
+                    "lucide-react": "^0.552.0"
+                })
+            elif template_name == "carousel":
+                template_deps.update({
+                    "lucide-react": "^0.552.0",
+                    "embla-carousel-react": "^8.6.0"
+                })
+            elif template_name == "albums":
+                template_deps.update({
+                    "lucide-react": "^0.552.0",
+                    "embla-carousel-react": "^8.6.0"
+                })
+
+            # Check if dependencies already exist
+            deps_to_install = []
+            for dep, version in template_dev_deps.items():
+                if dep not in package_data['devDependencies']:
+                    package_data['devDependencies'][dep] = version
+                    deps_to_install.append(dep)
+
+            for dep, version in template_deps.items():
+                if dep not in package_data['dependencies']:
+                    package_data['dependencies'][dep] = version
+                    deps_to_install.append(dep)
+
+            # Write updated package.json
+            if deps_to_install:
+                with open(package_json_path, 'w') as f:
+                    json.dump(package_data, f, indent=2)
+
+                console.print(f"[cyan]Added {len(deps_to_install)} dependencies to package.json[/cyan]")
+
+                # Run npm install
+                console.print("[cyan]Running npm install...[/cyan]")
+                try:
+                    result = subprocess.run(
+                        ["npm", "install"],
+                        capture_output=True,
+                        text=True,
+                        check=True
+                    )
+                    console.print(f"[green]✓ {dep_name} dependencies installed[/green]")
+                except subprocess.CalledProcessError as e:
+                    console.print("[yellow]⚠ npm install failed. Run 'npm install' manually[/yellow]")
+                except FileNotFoundError:
+                    console.print("[yellow]⚠ npm not found. Run 'npm install' manually[/yellow]")
             else:
-                console.print("[yellow]Please install Tailwind CSS manually:[/yellow]")
-                console.print("[dim]  npm install -D @tailwindcss/vite tailwindcss autoprefixer postcss[/dim]")
+                console.print(f"[green]✓ {dep_name} dependencies already installed[/green]")
+
+        except Exception as e:
+            console.print(f"[yellow]⚠ Could not update package.json: {e}[/yellow]")
+            console.print("[yellow]Please install dependencies manually:[/yellow]")
+            manual_deps = ["@openai/apps-sdk-ui"]
+            if template_name in ["carousel", "albums"]:
+                manual_deps.extend(["embla-carousel-react", "lucide-react"])
+            elif template_name == "list":
+                manual_deps.append("lucide-react")
+            console.print(f"[dim]  npm install {' '.join(manual_deps)}[/dim]")
+            console.print("[dim]  npm install -D @tailwindcss/vite tailwindcss autoprefixer postcss[/dim]")
     else:
-        console.print(f"\n[green][OK] Widget '{name}' created![/green]")
+        console.print("[yellow]⚠ package.json not found[/yellow]")
+        manual_deps = ["@openai/apps-sdk-ui"]
+        if template_name in ["carousel", "albums"]:
+            manual_deps.extend(["embla-carousel-react", "lucide-react"])
+        elif template_name == "list":
+            manual_deps.append("lucide-react")
+        console.print("[yellow]Please install dependencies manually:[/yellow]")
+        console.print(f"[dim]  npm install {' '.join(manual_deps)}[/dim]")
+        console.print("[dim]  npm install -D @tailwindcss/vite tailwindcss autoprefixer postcss[/dim]")
 
     console.print("\n[green][OK] Widget created successfully![/green]")
     console.print("\n[cyan]Created files:[/cyan]")

From 7eaa80b464197b7a23cf1c37e03d1f55ae92bafc Mon Sep 17 00:00:00 2001
From: chaewon-huh <cw.huh@postech.ac.kr>
Date: Mon, 24 Nov 2025 00:12:21 +0900
Subject: [PATCH 2/9] chore: add apps-sdk-ui tailwind base to templates

---
 fastapps/templates/albums/widget/index.css   | 43 ++------------------
 fastapps/templates/carousel/widget/index.css | 43 ++------------------
 fastapps/templates/default/widget/index.css  |  3 ++
 fastapps/templates/list/widget/index.css     | 43 ++------------------
 4 files changed, 12 insertions(+), 120 deletions(-)
 create mode 100644 fastapps/templates/default/widget/index.css

diff --git a/fastapps/templates/albums/widget/index.css b/fastapps/templates/albums/widget/index.css
index 7b9c76c..a895ecb 100644
--- a/fastapps/templates/albums/widget/index.css
+++ b/fastapps/templates/albums/widget/index.css
@@ -1,40 +1,3 @@
-@import "tailwindcss" source(".");
-
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-
-@layer utilities {
-  .overflow-auto > *,
-  .overflow-scroll > *,
-  .overflow-x-auto > *,
-  .overflow-y-auto > * {
-    scrollbar-color: auto;
-  }
-
-  /* Base style for scrollable elements */
-  .overflow-auto,
-  .overflow-scroll,
-  .overflow-x-auto,
-  .overflow-y-auto,
-  .overflow-x-scroll,
-  .overflow-y-scroll {
-    scrollbar-color: rgb(0, 0, 0, 0.1) transparent;
-
-    @media (prefers-color-scheme: dark) {
-      scrollbar-color: rgb(255, 255, 255, 0.1) transparent;
-    }
-  }
-
-  /* Hover state directly on the scrollable element */
-  .overflow-auto:hover,
-  .overflow-scroll:hover,
-  .overflow-x-auto:hover,
-  .overflow-y-auto:hover {
-    scrollbar-color: rgb(0, 0, 0, 0.2) transparent;
-
-    @media (prefers-color-scheme: dark) {
-      scrollbar-color: rgb(255, 255, 255, 0.2) transparent;
-    }
-  }
-}
+@import "tailwindcss";
+@import "@openai/apps-sdk-ui/css";
+@source "../node_modules/@openai/apps-sdk-ui";
diff --git a/fastapps/templates/carousel/widget/index.css b/fastapps/templates/carousel/widget/index.css
index 7b9c76c..a895ecb 100644
--- a/fastapps/templates/carousel/widget/index.css
+++ b/fastapps/templates/carousel/widget/index.css
@@ -1,40 +1,3 @@
-@import "tailwindcss" source(".");
-
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-
-@layer utilities {
-  .overflow-auto > *,
-  .overflow-scroll > *,
-  .overflow-x-auto > *,
-  .overflow-y-auto > * {
-    scrollbar-color: auto;
-  }
-
-  /* Base style for scrollable elements */
-  .overflow-auto,
-  .overflow-scroll,
-  .overflow-x-auto,
-  .overflow-y-auto,
-  .overflow-x-scroll,
-  .overflow-y-scroll {
-    scrollbar-color: rgb(0, 0, 0, 0.1) transparent;
-
-    @media (prefers-color-scheme: dark) {
-      scrollbar-color: rgb(255, 255, 255, 0.1) transparent;
-    }
-  }
-
-  /* Hover state directly on the scrollable element */
-  .overflow-auto:hover,
-  .overflow-scroll:hover,
-  .overflow-x-auto:hover,
-  .overflow-y-auto:hover {
-    scrollbar-color: rgb(0, 0, 0, 0.2) transparent;
-
-    @media (prefers-color-scheme: dark) {
-      scrollbar-color: rgb(255, 255, 255, 0.2) transparent;
-    }
-  }
-}
+@import "tailwindcss";
+@import "@openai/apps-sdk-ui/css";
+@source "../node_modules/@openai/apps-sdk-ui";
diff --git a/fastapps/templates/default/widget/index.css b/fastapps/templates/default/widget/index.css
new file mode 100644
index 0000000..a895ecb
--- /dev/null
+++ b/fastapps/templates/default/widget/index.css
@@ -0,0 +1,3 @@
+@import "tailwindcss";
+@import "@openai/apps-sdk-ui/css";
+@source "../node_modules/@openai/apps-sdk-ui";
diff --git a/fastapps/templates/list/widget/index.css b/fastapps/templates/list/widget/index.css
index 7b9c76c..a895ecb 100644
--- a/fastapps/templates/list/widget/index.css
+++ b/fastapps/templates/list/widget/index.css
@@ -1,40 +1,3 @@
-@import "tailwindcss" source(".");
-
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-
-@layer utilities {
-  .overflow-auto > *,
-  .overflow-scroll > *,
-  .overflow-x-auto > *,
-  .overflow-y-auto > * {
-    scrollbar-color: auto;
-  }
-
-  /* Base style for scrollable elements */
-  .overflow-auto,
-  .overflow-scroll,
-  .overflow-x-auto,
-  .overflow-y-auto,
-  .overflow-x-scroll,
-  .overflow-y-scroll {
-    scrollbar-color: rgb(0, 0, 0, 0.1) transparent;
-
-    @media (prefers-color-scheme: dark) {
-      scrollbar-color: rgb(255, 255, 255, 0.1) transparent;
-    }
-  }
-
-  /* Hover state directly on the scrollable element */
-  .overflow-auto:hover,
-  .overflow-scroll:hover,
-  .overflow-x-auto:hover,
-  .overflow-y-auto:hover {
-    scrollbar-color: rgb(0, 0, 0, 0.2) transparent;
-
-    @media (prefers-color-scheme: dark) {
-      scrollbar-color: rgb(255, 255, 255, 0.2) transparent;
-    }
-  }
-}
+@import "tailwindcss";
+@import "@openai/apps-sdk-ui/css";
+@source "../node_modules/@openai/apps-sdk-ui";

From 3fa532af94026ebb7a93b6dc59e3049ccfe62249 Mon Sep 17 00:00:00 2001
From: chaewon-huh <cw.huh@postech.ac.kr>
Date: Mon, 24 Nov 2025 00:20:29 +0900
Subject: [PATCH 3/9] fix: avoid duplicate albums component name

---
 fastapps/templates/albums/widget/index.jsx | 53 +++++++++++++---------
 1 file changed, 31 insertions(+), 22 deletions(-)

diff --git a/fastapps/templates/albums/widget/index.jsx b/fastapps/templates/albums/widget/index.jsx
index 3117db3..bb14117 100644
--- a/fastapps/templates/albums/widget/index.jsx
+++ b/fastapps/templates/albums/widget/index.jsx
@@ -1,4 +1,7 @@
 import React from "react";
+import { AppsSDKUIProvider } from "@openai/apps-sdk-ui/components/AppsSDKUIProvider";
+import { Button } from "@openai/apps-sdk-ui/components/Button";
+import { EmptyMessage } from "@openai/apps-sdk-ui/components/EmptyMessage";
 import { useWidgetProps, useMaxHeight, useOpenAiGlobal } from "fastapps";
 import useEmblaCarousel from "embla-carousel-react";
 import { ArrowLeft, ArrowRight } from "lucide-react";
@@ -39,9 +42,9 @@ function AlbumsCarousel({ albums, onSelect }) {
   if (!hasAlbums) {
     return (
       <div className="antialiased relative w-full py-5">
-        <div className="text-center text-sm text-black/80 dark:text-white/80 py-6">
+        <EmptyMessage>
           No albums available. Provide up to 8 entries for best results.
-        </div>
+        </EmptyMessage>
       </div>
     );
   }
@@ -61,38 +64,38 @@ function AlbumsCarousel({ albums, onSelect }) {
         </div>
       </div>
       {canPrev && (
-        <button
+        <Button
           aria-label="Previous"
-          className="absolute left-2 top-1/2 -translate-y-1/2 z-10 inline-flex items-center justify-center h-8 w-8 rounded-full bg-white text-black shadow-sm ring-1 ring-black/10 hover:bg-black/5 dark:bg-white/10 dark:text-white dark:ring-white/20 dark:hover:bg-white/20"
+          className="absolute left-2 top-1/2 -translate-y-1/2 z-10"
+          variant="outline"
+          color="secondary"
+          size="sm"
+          uniform
+          pill
           onClick={() => emblaApi && emblaApi.scrollPrev()}
-          type="button"
         >
-          <ArrowLeft
-            strokeWidth={1.5}
-            className="h-4.5 w-4.5"
-            aria-hidden="true"
-          />
-        </button>
+          <ArrowLeft strokeWidth={1.5} className="h-4 w-4" aria-hidden="true" />
+        </Button>
       )}
       {canNext && (
-        <button
+        <Button
           aria-label="Next"
-          className="absolute right-2 top-1/2 -translate-y-1/2 z-10 inline-flex items-center justify-center h-8 w-8 rounded-full bg-white text-black shadow-sm ring-1 ring-black/10 hover:bg-black/5 dark:bg-white/10 dark:text-white dark:ring-white/20 dark:hover:bg-white/20"
+          className="absolute right-2 top-1/2 -translate-y-1/2 z-10"
+          variant="outline"
+          color="secondary"
+          size="sm"
+          uniform
+          pill
           onClick={() => emblaApi && emblaApi.scrollNext()}
-          type="button"
         >
-          <ArrowRight
-            strokeWidth={1.5}
-            className="h-4.5 w-4.5"
-            aria-hidden="true"
-          />
-        </button>
+          <ArrowRight strokeWidth={1.5} className="h-4 w-4" aria-hidden="true" />
+        </Button>
       )}
     </div>
   );
 }
 
-function {ClassName}() {
+function {ClassName}Inner() {
   const { albums } = useWidgetProps() || {};
   const normalizedAlbums = Array.isArray(albums)
     ? albums
@@ -160,4 +163,10 @@ function {ClassName}() {
   );
 }
 
-export default {ClassName};
+export default function {ClassName}() {
+  return (
+    <AppsSDKUIProvider>
+      <{ClassName}Inner />
+    </AppsSDKUIProvider>
+  );
+}

From 57fb5329528513388c3a3864154255d78c36e3b7 Mon Sep 17 00:00:00 2001
From: chaewon-huh <cw.huh@postech.ac.kr>
Date: Mon, 24 Nov 2025 00:21:48 +0900
Subject: [PATCH 4/9] feat: port templates to apps-sdk-ui components

---
 .../templates/albums/widget/AlbumCard.jsx     | 18 +++---
 .../albums/widget/FullscreenViewer.jsx        | 19 ++++---
 fastapps/templates/carousel/widget/Card.jsx   |  8 +--
 fastapps/templates/carousel/widget/index.jsx  | 53 ++++++++++--------
 fastapps/templates/default/widget/index.jsx   | 37 ++++++++----
 fastapps/templates/list/widget/index.jsx      | 56 +++++++++++--------
 6 files changed, 113 insertions(+), 78 deletions(-)

diff --git a/fastapps/templates/albums/widget/AlbumCard.jsx b/fastapps/templates/albums/widget/AlbumCard.jsx
index 4a01433..fb9bae6 100644
--- a/fastapps/templates/albums/widget/AlbumCard.jsx
+++ b/fastapps/templates/albums/widget/AlbumCard.jsx
@@ -1,4 +1,5 @@
 import React from "react";
+import { Button } from "@openai/apps-sdk-ui/components/Button";
 
 function AlbumCard({ album, onSelect }) {
   if (!album) return null;
@@ -8,13 +9,16 @@ function AlbumCard({ album, onSelect }) {
   const title = album.title || "Album";
 
   return (
-    <button
+    <Button
       type="button"
-      className="group relative cursor-pointer flex-shrink-0 w-[272px] bg-transparent text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-black/40 dark:focus-visible:ring-white/40 rounded-3xl"
+      variant="ghost"
+      color="secondary"
+      className="group relative cursor-pointer flex-shrink-0 w-[272px] bg-transparent text-left rounded-3xl p-0 focus-visible:ring-2 focus-visible:ring-default"
       onClick={() => onSelect?.(album)}
       aria-label={`Open ${title}`}
+      block
     >
-      <div className="aspect-[4/3] w-full overflow-hidden rounded-2xl shadow-lg">
+      <div className="aspect-[4/3] w-full overflow-hidden rounded-2xl shadow-card bg-surface">
         <img
           src={album.cover}
           alt={title}
@@ -22,11 +26,11 @@ function AlbumCard({ album, onSelect }) {
           loading="lazy"
         />
       </div>
-      <div className="pt-3 px-1.5">
-        <div className="text-base font-medium truncate text-black dark:text-white">{title}</div>
-        <div className="text-sm text-black/80 dark:text-white/80 mt-0.5">{photoSummary}</div>
+      <div className="pt-3 px-1.5 w-full">
+        <div className="text-base font-medium truncate text-foreground">{title}</div>
+        <div className="text-sm text-secondary mt-0.5">{photoSummary}</div>
       </div>
-    </button>
+    </Button>
   );
 }
 
diff --git a/fastapps/templates/albums/widget/FullscreenViewer.jsx b/fastapps/templates/albums/widget/FullscreenViewer.jsx
index 6ca4b2c..531acc6 100644
--- a/fastapps/templates/albums/widget/FullscreenViewer.jsx
+++ b/fastapps/templates/albums/widget/FullscreenViewer.jsx
@@ -1,4 +1,5 @@
 import React from "react";
+import { Button } from "@openai/apps-sdk-ui/components/Button";
 import { ArrowLeft } from "lucide-react";
 import { useMaxHeight } from "fastapps";
 import FilmStrip from "./FilmStrip";
@@ -34,18 +35,18 @@ export default function FullscreenViewer({ album, onBack }) {
     >
       {/* Back button */}
       {onBack && (
-        <button
+        <Button
           aria-label="Back to albums"
-          className="absolute left-4 top-4 z-20 inline-flex items-center justify-center h-10 w-10 rounded-full bg-white text-black shadow-lg ring ring-black/5 hover:bg-gray-50 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-black/40"
+          className="absolute left-4 top-4 z-20 shadow-lg"
+          variant="outline"
+          color="secondary"
+          size="md"
+          uniform
+          pill
           onClick={onBack}
-          type="button"
         >
-          <ArrowLeft
-            strokeWidth={1.5}
-            className="h-5 w-5"
-            aria-hidden="true"
-          />
-        </button>
+          <ArrowLeft strokeWidth={1.5} className="h-4 w-4" aria-hidden="true" />
+        </Button>
       )}
 
       <div className="absolute inset-0 flex flex-row overflow-hidden">
diff --git a/fastapps/templates/carousel/widget/Card.jsx b/fastapps/templates/carousel/widget/Card.jsx
index 51932cb..c19457f 100644
--- a/fastapps/templates/carousel/widget/Card.jsx
+++ b/fastapps/templates/carousel/widget/Card.jsx
@@ -1,4 +1,5 @@
 import React from "react";
+import { Button } from "@openai/apps-sdk-ui/components/Button";
 import { Star } from "lucide-react";
 
 export default function Card({ card }) {
@@ -27,12 +28,9 @@ export default function Card({ card }) {
           </div>
         ) : null}
         <div className="mt-5">
-          <button
-            type="button"
-            className="cursor-pointer inline-flex items-center rounded-full border px-4 py-1.5 text-sm font-medium bg-white text-black border-black/20 hover:bg-black/5 active:bg-black/10 dark:bg-white/10 dark:text-white dark:border-white/20 dark:hover:bg-white/20 dark:active:bg-white/30"
-          >
+          <Button variant="soft" color="secondary" size="sm" pill>
             Learn more
-          </button>
+          </Button>
         </div>
       </div>
     </div>
diff --git a/fastapps/templates/carousel/widget/index.jsx b/fastapps/templates/carousel/widget/index.jsx
index a1f8252..7a20457 100644
--- a/fastapps/templates/carousel/widget/index.jsx
+++ b/fastapps/templates/carousel/widget/index.jsx
@@ -1,11 +1,14 @@
 import React from "react";
+import { AppsSDKUIProvider } from "@openai/apps-sdk-ui/components/AppsSDKUIProvider";
+import { Button } from "@openai/apps-sdk-ui/components/Button";
+import { EmptyMessage } from "@openai/apps-sdk-ui/components/EmptyMessage";
 import { useWidgetProps } from "fastapps";
 import useEmblaCarousel from "embla-carousel-react";
 import { ArrowLeft, ArrowRight } from "lucide-react";
 import Card from "./Card";
 import "./index.css";
 
-function {ClassName}() {
+function {ClassName}Inner() {
   const { cards } = useWidgetProps() || {};
 
   const normalizedCards = Array.isArray(cards) ? cards : [];
@@ -41,9 +44,9 @@ function {ClassName}() {
   if (!hasCards) {
     return (
       <div className="antialiased relative w-full py-5">
-        <div className="text-center text-sm text-black/80 dark:text-white/80 py-6">
+        <EmptyMessage>
           No items to display. Provide up to 8 entries for best results.
-        </div>
+        </EmptyMessage>
       </div>
     );
   }
@@ -63,35 +66,41 @@ function {ClassName}() {
         </div>
       </div>
       {canPrev && (
-        <button
+        <Button
           aria-label="Previous carousel item"
-          className="absolute left-2 top-1/2 -translate-y-1/2 z-10 inline-flex items-center justify-center h-8 w-8 rounded-full bg-white text-black shadow-sm ring-1 ring-black/10 hover:bg-black/5 dark:bg-white/10 dark:text-white dark:ring-white/20 dark:hover:bg-white/20"
+          className="absolute left-2 top-1/2 -translate-y-1/2 z-10"
+          variant="outline"
+          color="secondary"
+          size="sm"
+          uniform
+          pill
           onClick={() => emblaApi && emblaApi.scrollPrev()}
-          type="button"
         >
-          <ArrowLeft
-            strokeWidth={1.5}
-            className="h-4.5 w-4.5"
-            aria-hidden="true"
-          />
-        </button>
+          <ArrowLeft strokeWidth={1.5} className="h-4 w-4" aria-hidden="true" />
+        </Button>
       )}
       {canNext && (
-        <button
+        <Button
           aria-label="Next carousel item"
-          className="absolute right-2 top-1/2 -translate-y-1/2 z-10 inline-flex items-center justify-center h-8 w-8 rounded-full bg-white text-black shadow-sm ring-1 ring-black/10 hover:bg-black/5 dark:bg-white/10 dark:text-white dark:ring-white/20 dark:hover:bg-white/20"
+          className="absolute right-2 top-1/2 -translate-y-1/2 z-10"
+          variant="outline"
+          color="secondary"
+          size="sm"
+          uniform
+          pill
           onClick={() => emblaApi && emblaApi.scrollNext()}
-          type="button"
         >
-          <ArrowRight
-            strokeWidth={1.5}
-            className="h-4.5 w-4.5"
-            aria-hidden="true"
-          />
-        </button>
+          <ArrowRight strokeWidth={1.5} className="h-4 w-4" aria-hidden="true" />
+        </Button>
       )}
     </div>
   );
 }
 
-export default {ClassName};
+export default function {ClassName}() {
+  return (
+    <AppsSDKUIProvider>
+      <{ClassName}Inner />
+    </AppsSDKUIProvider>
+  );
+}
diff --git a/fastapps/templates/default/widget/index.jsx b/fastapps/templates/default/widget/index.jsx
index aed094b..560b7c7 100644
--- a/fastapps/templates/default/widget/index.jsx
+++ b/fastapps/templates/default/widget/index.jsx
@@ -1,19 +1,32 @@
-import React from 'react';
-import { useWidgetProps } from 'fastapps';
+import React from "react";
+import { AppsSDKUIProvider } from "@openai/apps-sdk-ui/components/AppsSDKUIProvider";
+import { Badge } from "@openai/apps-sdk-ui/components/Badge";
+import { useWidgetProps } from "fastapps";
 
-export default function {ClassName}() {
+function {ClassName}Inner() {
   const { message } = useWidgetProps() || {};
 
   return (
-    <div style={{
-      background: '#000',
-      color: '#fff',
-      padding: '40px',
-      textAlign: 'center',
-      borderRadius: '8px',
-      fontFamily: 'monospace'
-    }}>
-      <h1>{message || 'Welcome to FastApps'}</h1>
+    <div className="w-full rounded-3xl border border-default bg-surface shadow-card p-6 sm:p-8 text-left">
+      <div className="flex items-start justify-between gap-3">
+        <div>
+          <p className="text-secondary text-sm">FastApps Widget</p>
+          <h1 className="mt-1 heading-lg">{message || "Welcome to FastApps"}</h1>
+        </div>
+        <Badge color="info">Template</Badge>
+      </div>
+      <p className="mt-4 text-secondary text-sm leading-relaxed">
+        Edit <code>server/tools</code> for logic and <code>widgets/{`{identifier}`}</code> for UI. Apps
+        SDK UI is prewired—swap this content with your own.
+      </p>
     </div>
   );
 }
+
+export default function {ClassName}() {
+  return (
+    <AppsSDKUIProvider>
+      <{ClassName}Inner />
+    </AppsSDKUIProvider>
+  );
+}
diff --git a/fastapps/templates/list/widget/index.jsx b/fastapps/templates/list/widget/index.jsx
index 8cd7be6..9d7ab4a 100644
--- a/fastapps/templates/list/widget/index.jsx
+++ b/fastapps/templates/list/widget/index.jsx
@@ -1,56 +1,56 @@
 import React from "react";
+import { AppsSDKUIProvider } from "@openai/apps-sdk-ui/components/AppsSDKUIProvider";
+import { Button } from "@openai/apps-sdk-ui/components/Button";
+import { EmptyMessage } from "@openai/apps-sdk-ui/components/EmptyMessage";
 import { useWidgetProps } from "fastapps";
 import { PlusCircle, Star } from "lucide-react";
 import "./index.css";
 
-function {ClassName}() {
+function {ClassName}Inner() {
   const { title, description, items } = useWidgetProps() || {};
   const normalizedItems = Array.isArray(items) ? items.slice(0, 7) : [];
   const hasItems = normalizedItems.length > 0;
 
   return (
-    <div className="antialiased w-full text-black dark:text-white px-4 pb-2 border border-black/10 dark:border-white/10 rounded-2xl sm:rounded-3xl overflow-hidden bg-white dark:bg-white/5">
+    <div className="antialiased w-full text-foreground px-4 pb-2 border border-default rounded-3xl overflow-hidden bg-surface shadow-card">
       <div className="max-w-full">
-        <div className="flex flex-col sm:flex-row sm:items-center gap-4 border-b border-black/5 dark:border-white/10 py-4">
+        <div className="flex flex-col sm:flex-row sm:items-center gap-4 border-b border-subtle py-4">
           <div className="flex flex-col gap-1">
-            <div className="text-base sm:text-xl font-medium">
+            <div className="text-base sm:text-xl font-medium heading-md">
               {title || "List Title"}
             </div>
-            <div className="text-sm text-black/80 dark:text-white/80">
+            <div className="text-sm text-secondary">
               {description || "A list of items"}
             </div>
           </div>
           <div className="sm:ml-auto">
-            <button
-              type="button"
-              className="cursor-pointer inline-flex items-center rounded-full border border-black/20 dark:border-white/20 bg-white text-black dark:bg-white/10 dark:text-white px-4 py-1.5 text-sm font-medium hover:bg-black/5 active:bg-black/10 dark:hover:bg-white/20"
-            >
+            <Button variant="outline" color="secondary" size="sm" pill>
               Save list
-            </button>
+            </Button>
           </div>
         </div>
-        <ol className="min-w-full text-sm flex flex-col divide-y divide-black/10 dark:divide-white/10">
+        <ol className="min-w-full text-sm flex flex-col divide-y divide-subtle">
           {normalizedItems.map((item, i) => {
             const rank = i + 1;
             const infoText = item?.info || "–";
             return (
               <li key={item?.id || i} className="px-1 sm:px-2">
                 <div className="flex w-full items-center gap-3 py-3">
-                  <div className="font-medium text-black/80 dark:text-white/80 hidden sm:block w-4 text-right">
+                  <div className="font-medium text-secondary hidden sm:block w-4 text-right">
                     {rank}
                   </div>
                   <div className="flex items-center gap-3 min-w-0 flex-1">
                     <img
                       src={item?.thumbnail || "https://via.placeholder.com/44"}
                       alt={item?.name || `Item ${rank}`}
-                      className="h-10 w-10 sm:h-11 sm:w-11 rounded-lg object-cover ring ring-black/5 dark:ring-white/10"
+                      className="h-10 w-10 sm:h-11 sm:w-11 rounded-lg object-cover ring-1 ring-default"
                       loading="lazy"
                     />
                     <div className="min-w-0 flex flex-col">
                       <div className="font-medium text-sm sm:text-base truncate max-w-[40ch]">
                         {item?.name || `Item ${rank}`}
                       </div>
-                      <div className="mt-1 flex items-center gap-3 text-black/80 dark:text-white/80 text-sm">
+                      <div className="mt-1 flex items-center gap-3 text-secondary text-sm">
                         <div className="flex items-center gap-1">
                           <Star strokeWidth={1.5} className="h-3 w-3" aria-hidden="true" />
                           <span>
@@ -63,18 +63,20 @@ function {ClassName}() {
                       </div>
                     </div>
                   </div>
-                  <div className="hidden sm:block text-sm text-black/80 dark:text-white/80 whitespace-nowrap">
+                  <div className="hidden sm:block text-sm text-secondary whitespace-nowrap">
                     {infoText}
                   </div>
                   <div className="flex justify-end">
-                    <button
-                      type="button"
-                      className="inline-flex items-center gap-1 rounded-full border border-black/20 dark:border-white/20 px-3 py-1 text-sm font-medium text-black dark:text-white hover:bg-black/5 active:bg-black/10 dark:hover:bg-white/20"
+                    <Button
+                      variant="outline"
+                      color="secondary"
+                      size="sm"
+                      pill
                       aria-label={`Add ${item?.name || `item ${rank}`} to list`}
                     >
                       <PlusCircle strokeWidth={1.5} className="h-4 w-4" aria-hidden="true" />
-                      <span>Add</span>
-                    </button>
+                      Add
+                    </Button>
                   </div>
                 </div>
               </li>
@@ -82,8 +84,10 @@ function {ClassName}() {
           })}
         </ol>
         {!hasItems && (
-          <div className="py-6 text-center text-black/80 dark:text-white/80">
-            No items available. Provide up to 7 entries for best results.
+          <div className="py-6">
+            <EmptyMessage>
+              No items available. Provide up to 7 entries for best results.
+            </EmptyMessage>
           </div>
         )}
       </div>
@@ -91,4 +95,10 @@ function {ClassName}() {
   );
 }
 
-export default {ClassName};
+export default function {ClassName}() {
+  return (
+    <AppsSDKUIProvider>
+      <{ClassName}Inner />
+    </AppsSDKUIProvider>
+  );
+}

From dc5c0ebc6fcf9c67dd7acb2267ca1d4f5935b888 Mon Sep 17 00:00:00 2001
From: chaewon-huh <cw.huh@postech.ac.kr>
Date: Mon, 24 Nov 2025 00:34:13 +0900
Subject: [PATCH 5/9] chore: refine apps-sdk-ui visuals in templates

---
 fastapps/templates/albums/widget/AlbumCard.jsx      | 11 +++++++----
 fastapps/templates/albums/widget/FilmStrip.jsx      |  9 +++++----
 .../templates/albums/widget/FullscreenViewer.jsx    | 13 +++++++++----
 fastapps/templates/albums/widget/index.jsx          |  6 +++---
 fastapps/templates/carousel/widget/Card.jsx         | 11 ++++++-----
 fastapps/templates/list/widget/index.jsx            |  5 +++--
 6 files changed, 33 insertions(+), 22 deletions(-)

diff --git a/fastapps/templates/albums/widget/AlbumCard.jsx b/fastapps/templates/albums/widget/AlbumCard.jsx
index fb9bae6..5f4fbda 100644
--- a/fastapps/templates/albums/widget/AlbumCard.jsx
+++ b/fastapps/templates/albums/widget/AlbumCard.jsx
@@ -1,5 +1,6 @@
 import React from "react";
 import { Button } from "@openai/apps-sdk-ui/components/Button";
+import { Image } from "@openai/apps-sdk-ui/components/Image";
 
 function AlbumCard({ album, onSelect }) {
   if (!album) return null;
@@ -18,16 +19,18 @@ function AlbumCard({ album, onSelect }) {
       aria-label={`Open ${title}`}
       block
     >
-      <div className="aspect-[4/3] w-full overflow-hidden rounded-2xl shadow-card bg-surface">
-        <img
+      <div className="w-full overflow-hidden rounded-2xl shadow-card bg-surface">
+        <Image
           src={album.cover}
           alt={title}
-          className="h-full w-full object-cover"
+          className="w-full h-auto"
           loading="lazy"
         />
       </div>
       <div className="pt-3 px-1.5 w-full">
-        <div className="text-base font-medium truncate text-foreground">{title}</div>
+        <div className="text-base font-medium truncate text-foreground">
+          {title}
+        </div>
         <div className="text-sm text-secondary mt-0.5">{photoSummary}</div>
       </div>
     </Button>
diff --git a/fastapps/templates/albums/widget/FilmStrip.jsx b/fastapps/templates/albums/widget/FilmStrip.jsx
index 1a7772a..ab4d9e6 100644
--- a/fastapps/templates/albums/widget/FilmStrip.jsx
+++ b/fastapps/templates/albums/widget/FilmStrip.jsx
@@ -1,4 +1,5 @@
 import React from "react";
+import { Image } from "@openai/apps-sdk-ui/components/Image";
 
 export default function FilmStrip({ album, selectedIndex, onSelect }) {
   if (!album?.photos?.length) {
@@ -13,16 +14,16 @@ export default function FilmStrip({ album, selectedIndex, onSelect }) {
           type="button"
           onClick={() => onSelect?.(idx)}
           className={
-            "block w-full p-[1px] pointer-events-auto rounded-xl cursor-pointer border transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-black/40 dark:focus-visible:ring-white/40 " +
+            "block w-full p-[1px] pointer-events-auto rounded-xl cursor-pointer border transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-default " +
             (idx === selectedIndex
-              ? "border-black bg-black/5 dark:border-white dark:bg-white/10"
-              : "border-black/10 hover:border-black/50 dark:border-white/20 dark:hover:border-white/60")
+              ? "border-strong bg-primary-soft-alpha"
+              : "border-default hover:border-strong")
           }
           aria-pressed={idx === selectedIndex}
           aria-label={`View ${photo.title || `photo ${idx + 1}`}`}
         >
           <div className="aspect-[5/3] rounded-lg overflow-hidden w-full">
-            <img
+            <Image
               src={photo.url}
               alt={photo.title || `Photo ${idx + 1}`}
               className="h-full w-full object-cover"
diff --git a/fastapps/templates/albums/widget/FullscreenViewer.jsx b/fastapps/templates/albums/widget/FullscreenViewer.jsx
index 531acc6..65c28bd 100644
--- a/fastapps/templates/albums/widget/FullscreenViewer.jsx
+++ b/fastapps/templates/albums/widget/FullscreenViewer.jsx
@@ -1,5 +1,6 @@
 import React from "react";
 import { Button } from "@openai/apps-sdk-ui/components/Button";
+import { Image } from "@openai/apps-sdk-ui/components/Image";
 import { ArrowLeft } from "lucide-react";
 import { useMaxHeight } from "fastapps";
 import FilmStrip from "./FilmStrip";
@@ -27,7 +28,7 @@ export default function FullscreenViewer({ album, onBack }) {
 
   return (
     <div
-      className="relative w-full h-full bg-white"
+      className="relative w-full h-full bg-surface"
       style={{
         maxHeight,
         height: maxHeight,
@@ -52,16 +53,20 @@ export default function FullscreenViewer({ album, onBack }) {
       <div className="absolute inset-0 flex flex-row overflow-hidden">
         {/* Film strip */}
         <div className="hidden md:block absolute pointer-events-none z-10 left-0 top-0 bottom-0 w-40">
-          <FilmStrip album={{ ...album, photos }} selectedIndex={index} onSelect={setIndex} />
+          <FilmStrip
+            album={{ ...album, photos }}
+            selectedIndex={index}
+            onSelect={setIndex}
+          />
         </div>
         {/* Main photo */}
         <div className="flex-1 min-w-0 px-40 py-10 relative flex items-center justify-center">
           <div className="relative w-full h-full">
             {photo ? (
-              <img
+              <Image
                 src={photo.url}
                 alt={photo.title || album.title || "Photo"}
-                className="absolute inset-0 m-auto rounded-3xl shadow-sm border border-black/10 max-w-full max-h-full object-contain"
+                className="absolute inset-0 m-auto rounded-3xl shadow-sm border border-default max-w-full max-h-full object-contain"
               />
             ) : null}
           </div>
diff --git a/fastapps/templates/albums/widget/index.jsx b/fastapps/templates/albums/widget/index.jsx
index bb14117..bfc40ec 100644
--- a/fastapps/templates/albums/widget/index.jsx
+++ b/fastapps/templates/albums/widget/index.jsx
@@ -50,7 +50,7 @@ function AlbumsCarousel({ albums, onSelect }) {
   }
 
   return (
-    <div className="antialiased relative w-full text-black dark:text-white py-5 select-none">
+    <div className="antialiased relative w-full text-default py-5 select-none">
       <div className="overflow-hidden" ref={emblaRef}>
         <div className="flex gap-5 items-stretch">
           {normalizedAlbums.map((album, i) => (
@@ -142,9 +142,9 @@ function {ClassName}Inner() {
   return (
     <div
       className={
-        "relative antialiased w-full text-black dark:text-white " +
+        "relative antialiased w-full text-default " +
         (isFullscreen
-          ? "bg-white"
+          ? "bg-surface"
           : "bg-transparent overflow-hidden")
       }
       style={{
diff --git a/fastapps/templates/carousel/widget/Card.jsx b/fastapps/templates/carousel/widget/Card.jsx
index c19457f..a178275 100644
--- a/fastapps/templates/carousel/widget/Card.jsx
+++ b/fastapps/templates/carousel/widget/Card.jsx
@@ -1,5 +1,6 @@
 import React from "react";
 import { Button } from "@openai/apps-sdk-ui/components/Button";
+import { Image } from "@openai/apps-sdk-ui/components/Image";
 import { Star } from "lucide-react";
 
 export default function Card({ card }) {
@@ -7,23 +8,23 @@ export default function Card({ card }) {
   return (
     <div className="min-w-[220px] select-none max-w-[220px] w-[65vw] sm:w-[220px] self-stretch flex flex-col">
       <div className="w-full">
-        <img
+        <Image
           src={card.thumbnail}
           alt={card.name || card.description || "Carousel card"}
-          className="w-full aspect-square rounded-2xl object-cover ring ring-black/5 shadow-[0px_2px_6px_rgba(0,0,0,0.06)]"
+          className="w-full aspect-square rounded-2xl object-cover ring-1 ring-default shadow-sm"
         />
       </div>
       <div className="mt-3 flex flex-col flex-1">
-        <div className="text-base font-medium truncate line-clamp-1 text-black dark:text-white">
+        <div className="text-base font-medium truncate line-clamp-1 text-default">
           {card.name}
         </div>
-        <div className="text-xs mt-1 flex items-center gap-1 text-black/80 dark:text-white/80">
+        <div className="text-xs mt-1 flex items-center gap-1 text-secondary">
           <Star className="h-3 w-3" aria-hidden="true" />
           {card.rating?.toFixed ? card.rating.toFixed(1) : card.rating}
           {card.price ? <span>· {card.price}</span> : null}
         </div>
         {card.description ? (
-          <div className="text-sm mt-2 flex-auto text-black/80 dark:text-white/80">
+          <div className="text-sm mt-2 flex-auto text-secondary">
             {card.description}
           </div>
         ) : null}
diff --git a/fastapps/templates/list/widget/index.jsx b/fastapps/templates/list/widget/index.jsx
index 9d7ab4a..3b6bab8 100644
--- a/fastapps/templates/list/widget/index.jsx
+++ b/fastapps/templates/list/widget/index.jsx
@@ -2,6 +2,7 @@ import React from "react";
 import { AppsSDKUIProvider } from "@openai/apps-sdk-ui/components/AppsSDKUIProvider";
 import { Button } from "@openai/apps-sdk-ui/components/Button";
 import { EmptyMessage } from "@openai/apps-sdk-ui/components/EmptyMessage";
+import { Image } from "@openai/apps-sdk-ui/components/Image";
 import { useWidgetProps } from "fastapps";
 import { PlusCircle, Star } from "lucide-react";
 import "./index.css";
@@ -29,7 +30,7 @@ function {ClassName}Inner() {
             </Button>
           </div>
         </div>
-        <ol className="min-w-full text-sm flex flex-col divide-y divide-subtle">
+        <ol className="min-w-full text-sm flex flex-col divide-y divide-default">
           {normalizedItems.map((item, i) => {
             const rank = i + 1;
             const infoText = item?.info || "–";
@@ -40,7 +41,7 @@ function {ClassName}Inner() {
                     {rank}
                   </div>
                   <div className="flex items-center gap-3 min-w-0 flex-1">
-                    <img
+                    <Image
                       src={item?.thumbnail || "https://via.placeholder.com/44"}
                       alt={item?.name || `Item ${rank}`}
                       className="h-10 w-10 sm:h-11 sm:w-11 rounded-lg object-cover ring-1 ring-default"

From 0dad9976cc8d0efc3e62c382702ac0b173024d3d Mon Sep 17 00:00:00 2001
From: chaewon-huh <cw.huh@postech.ac.kr>
Date: Mon, 24 Nov 2025 00:46:42 +0900
Subject: [PATCH 6/9] chore: fix album cover aspect ratio

---
 fastapps/templates/albums/widget/AlbumCard.jsx | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/fastapps/templates/albums/widget/AlbumCard.jsx b/fastapps/templates/albums/widget/AlbumCard.jsx
index 5f4fbda..0f9d403 100644
--- a/fastapps/templates/albums/widget/AlbumCard.jsx
+++ b/fastapps/templates/albums/widget/AlbumCard.jsx
@@ -20,12 +20,14 @@ function AlbumCard({ album, onSelect }) {
       block
     >
       <div className="w-full overflow-hidden rounded-2xl shadow-card bg-surface">
-        <Image
-          src={album.cover}
-          alt={title}
-          className="w-full h-auto"
-          loading="lazy"
-        />
+        <div className="aspect-[4/3] w-full overflow-hidden">
+          <Image
+            src={album.cover}
+            alt={title}
+            className="w-full h-full object-cover"
+            loading="lazy"
+          />
+        </div>
       </div>
       <div className="pt-3 px-1.5 w-full">
         <div className="text-base font-medium truncate text-foreground">

From 0fe9bc1f063db098bc03a37ea31578c564103e0a Mon Sep 17 00:00:00 2001
From: chaewon-huh <cw.huh@postech.ac.kr>
Date: Mon, 24 Nov 2025 00:53:06 +0900
Subject: [PATCH 7/9] fix: respect maxHeight without clipping albums inline

---
 fastapps/templates/albums/widget/index.jsx | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/fastapps/templates/albums/widget/index.jsx b/fastapps/templates/albums/widget/index.jsx
index bfc40ec..38679d1 100644
--- a/fastapps/templates/albums/widget/index.jsx
+++ b/fastapps/templates/albums/widget/index.jsx
@@ -143,13 +143,12 @@ function {ClassName}Inner() {
     <div
       className={
         "relative antialiased w-full text-default " +
-        (isFullscreen
-          ? "bg-surface"
-          : "bg-transparent overflow-hidden")
+        (isFullscreen ? "bg-surface" : "bg-transparent")
       }
       style={{
-        maxHeight,
+        maxHeight: !isFullscreen ? maxHeight : undefined,
         height: isFullscreen ? maxHeight : undefined,
+        overflow: !isFullscreen ? "auto" : undefined,
       }}
     >
       {!isFullscreen && (

From 8d383a8a3b7ce0596ccbb0b5ce43b3acce7b3bb9 Mon Sep 17 00:00:00 2001
From: chaewon-huh <cw.huh@postech.ac.kr>
Date: Mon, 24 Nov 2025 10:11:02 +0900
Subject: [PATCH 8/9] fix: relax template layout constraints

---
 fastapps/templates/albums/widget/FullscreenViewer.jsx | 1 -
 fastapps/templates/albums/widget/index.jsx            | 2 --
 fastapps/templates/carousel/widget/Card.jsx           | 2 +-
 fastapps/templates/list/widget/index.jsx              | 4 ++--
 4 files changed, 3 insertions(+), 6 deletions(-)

diff --git a/fastapps/templates/albums/widget/FullscreenViewer.jsx b/fastapps/templates/albums/widget/FullscreenViewer.jsx
index 65c28bd..62ae699 100644
--- a/fastapps/templates/albums/widget/FullscreenViewer.jsx
+++ b/fastapps/templates/albums/widget/FullscreenViewer.jsx
@@ -31,7 +31,6 @@ export default function FullscreenViewer({ album, onBack }) {
       className="relative w-full h-full bg-surface"
       style={{
         maxHeight,
-        height: maxHeight,
       }}
     >
       {/* Back button */}
diff --git a/fastapps/templates/albums/widget/index.jsx b/fastapps/templates/albums/widget/index.jsx
index 38679d1..75a4dc0 100644
--- a/fastapps/templates/albums/widget/index.jsx
+++ b/fastapps/templates/albums/widget/index.jsx
@@ -146,8 +146,6 @@ function {ClassName}Inner() {
         (isFullscreen ? "bg-surface" : "bg-transparent")
       }
       style={{
-        maxHeight: !isFullscreen ? maxHeight : undefined,
-        height: isFullscreen ? maxHeight : undefined,
         overflow: !isFullscreen ? "auto" : undefined,
       }}
     >
diff --git a/fastapps/templates/carousel/widget/Card.jsx b/fastapps/templates/carousel/widget/Card.jsx
index a178275..69ebec5 100644
--- a/fastapps/templates/carousel/widget/Card.jsx
+++ b/fastapps/templates/carousel/widget/Card.jsx
@@ -11,7 +11,7 @@ export default function Card({ card }) {
         <Image
           src={card.thumbnail}
           alt={card.name || card.description || "Carousel card"}
-          className="w-full aspect-square rounded-2xl object-cover ring-1 ring-default shadow-sm"
+          className="w-full aspect-square rounded-2xl object-cover shadow-sm"
         />
       </div>
       <div className="mt-3 flex flex-col flex-1">
diff --git a/fastapps/templates/list/widget/index.jsx b/fastapps/templates/list/widget/index.jsx
index 3b6bab8..a5330d9 100644
--- a/fastapps/templates/list/widget/index.jsx
+++ b/fastapps/templates/list/widget/index.jsx
@@ -30,7 +30,7 @@ function {ClassName}Inner() {
             </Button>
           </div>
         </div>
-        <ol className="min-w-full text-sm flex flex-col divide-y divide-default">
+        <ol className="min-w-full text-sm flex flex-col">
           {normalizedItems.map((item, i) => {
             const rank = i + 1;
             const infoText = item?.info || "–";
@@ -44,7 +44,7 @@ function {ClassName}Inner() {
                     <Image
                       src={item?.thumbnail || "https://via.placeholder.com/44"}
                       alt={item?.name || `Item ${rank}`}
-                      className="h-10 w-10 sm:h-11 sm:w-11 rounded-lg object-cover ring-1 ring-default"
+                      className="h-10 w-10 sm:h-11 sm:w-11 rounded-lg object-cover"
                       loading="lazy"
                     />
                     <div className="min-w-0 flex flex-col">

From 9162c378377582f90bb1017e17b1390edb7b6dde Mon Sep 17 00:00:00 2001
From: chaewon-huh <cw.huh@postech.ac.kr>
Date: Mon, 24 Nov 2025 11:10:48 +0900
Subject: [PATCH 9/9] Fix albums layout clipping in inline and fullscreen

---
 .../templates/albums/widget/AlbumCard.jsx     |  3 +-
 .../albums/widget/FullscreenViewer.jsx        | 35 +++++++------------
 fastapps/templates/albums/widget/index.jsx    |  7 ++--
 3 files changed, 18 insertions(+), 27 deletions(-)

diff --git a/fastapps/templates/albums/widget/AlbumCard.jsx b/fastapps/templates/albums/widget/AlbumCard.jsx
index 0f9d403..298b5bd 100644
--- a/fastapps/templates/albums/widget/AlbumCard.jsx
+++ b/fastapps/templates/albums/widget/AlbumCard.jsx
@@ -14,7 +14,8 @@ function AlbumCard({ album, onSelect }) {
       type="button"
       variant="ghost"
       color="secondary"
-      className="group relative cursor-pointer flex-shrink-0 w-[272px] bg-transparent text-left rounded-3xl p-0 focus-visible:ring-2 focus-visible:ring-default"
+      className="group relative cursor-pointer flex-shrink-0 w-[272px] bg-transparent text-left rounded-3xl p-0 focus-visible:ring-2 focus-visible:ring-default flex-col items-start"
+      style={{ height: "auto" }}
       onClick={() => onSelect?.(album)}
       aria-label={`Open ${title}`}
       block
diff --git a/fastapps/templates/albums/widget/FullscreenViewer.jsx b/fastapps/templates/albums/widget/FullscreenViewer.jsx
index 62ae699..f04b974 100644
--- a/fastapps/templates/albums/widget/FullscreenViewer.jsx
+++ b/fastapps/templates/albums/widget/FullscreenViewer.jsx
@@ -2,11 +2,9 @@ import React from "react";
 import { Button } from "@openai/apps-sdk-ui/components/Button";
 import { Image } from "@openai/apps-sdk-ui/components/Image";
 import { ArrowLeft } from "lucide-react";
-import { useMaxHeight } from "fastapps";
 import FilmStrip from "./FilmStrip";
 
 export default function FullscreenViewer({ album, onBack }) {
-  const maxHeight = useMaxHeight() ?? undefined;
   const [index, setIndex] = React.useState(0);
   const photos = Array.isArray(album?.photos) ? album.photos : [];
 
@@ -27,13 +25,7 @@ export default function FullscreenViewer({ album, onBack }) {
   const photo = photos[index];
 
   return (
-    <div
-      className="relative w-full h-full bg-surface"
-      style={{
-        maxHeight,
-      }}
-    >
-      {/* Back button */}
+    <div className="relative w-full bg-surface">
       {onBack && (
         <Button
           aria-label="Back to albums"
@@ -49,26 +41,23 @@ export default function FullscreenViewer({ album, onBack }) {
         </Button>
       )}
 
-      <div className="absolute inset-0 flex flex-row overflow-hidden">
-        {/* Film strip */}
-        <div className="hidden md:block absolute pointer-events-none z-10 left-0 top-0 bottom-0 w-40">
+      <div className="flex flex-col md:flex-row items-stretch gap-6 md:gap-10 px-4 sm:px-6 md:px-10 py-8 md:py-12">
+        <div className="hidden md:flex w-40 shrink-0">
           <FilmStrip
             album={{ ...album, photos }}
             selectedIndex={index}
             onSelect={setIndex}
           />
         </div>
-        {/* Main photo */}
-        <div className="flex-1 min-w-0 px-40 py-10 relative flex items-center justify-center">
-          <div className="relative w-full h-full">
-            {photo ? (
-              <Image
-                src={photo.url}
-                alt={photo.title || album.title || "Photo"}
-                className="absolute inset-0 m-auto rounded-3xl shadow-sm border border-default max-w-full max-h-full object-contain"
-              />
-            ) : null}
-          </div>
+
+        <div className="flex-1 min-w-0 flex items-center justify-center">
+          {photo ? (
+            <Image
+              src={photo.url}
+              alt={photo.title || album.title || "Photo"}
+              className="w-full max-h-[70vh] rounded-3xl shadow-sm border border-default object-contain"
+            />
+          ) : null}
         </div>
       </div>
     </div>
diff --git a/fastapps/templates/albums/widget/index.jsx b/fastapps/templates/albums/widget/index.jsx
index 75a4dc0..e4f6ab2 100644
--- a/fastapps/templates/albums/widget/index.jsx
+++ b/fastapps/templates/albums/widget/index.jsx
@@ -2,7 +2,7 @@ import React from "react";
 import { AppsSDKUIProvider } from "@openai/apps-sdk-ui/components/AppsSDKUIProvider";
 import { Button } from "@openai/apps-sdk-ui/components/Button";
 import { EmptyMessage } from "@openai/apps-sdk-ui/components/EmptyMessage";
-import { useWidgetProps, useMaxHeight, useOpenAiGlobal } from "fastapps";
+import { useWidgetProps, useOpenAiGlobal, useMaxHeight } from "fastapps";
 import useEmblaCarousel from "embla-carousel-react";
 import { ArrowLeft, ArrowRight } from "lucide-react";
 import FullscreenViewer from "./FullscreenViewer";
@@ -50,7 +50,7 @@ function AlbumsCarousel({ albums, onSelect }) {
   }
 
   return (
-    <div className="antialiased relative w-full text-default py-5 select-none">
+    <div className="antialiased relative w-full text-default py-5 select-none min-h-[260px]">
       <div className="overflow-hidden" ref={emblaRef}>
         <div className="flex gap-5 items-stretch">
           {normalizedAlbums.map((album, i) => (
@@ -146,7 +146,8 @@ function {ClassName}Inner() {
         (isFullscreen ? "bg-surface" : "bg-transparent")
       }
       style={{
-        overflow: !isFullscreen ? "auto" : undefined,
+        maxHeight: isFullscreen ? undefined : maxHeight,
+        overflow: isFullscreen ? "visible" : "auto",
       }}
     >
       {!isFullscreen && (