feat: add UI template system for saving and reusing generated widgets

- Add template tools (save, list, apply, delete) in agent backend
- Extend AgentState with templates field
- Add "Save as Template" button overlay on widget renderer with
  animated save flow (input → saving spinner → checkmark confirmation)
- Add template library drawer panel (toggle from header)
- Templates saved directly to agent state via setState (no chat round-trip)
- Template deletion from drawer updates state directly
- Apply template sends chat prompt for agent to adapt HTML with new data

Closes #16

Author: breadoncee

apps/agent/main.py

@@ -10,14 +10,15 @@
 from src.query import query_data
 from src.todos import AgentState, todo_tools
 from src.form import generate_form
+from src.templates import template_tools
 from skills import load_all_skills
 
 # Load all visualization skills
 _skills_text = load_all_skills()
 
 agent = create_agent(
     model=ChatOpenAI(model="gpt-5.4-2026-03-05"),
-    tools=[query_data, *todo_tools, generate_form],
+    tools=[query_data, *todo_tools, generate_form, *template_tools],
     middleware=[CopilotKitMiddleware()],
     state_schema=AgentState,
     system_prompt=f"""
@@ -47,6 +48,20 @@
         Follow the skills below for how to produce high-quality visuals:
 
         {_skills_text}
+
+        ## UI Templates
+
+        Users can save generated UIs as reusable templates and apply them later:
+
+        - When a user asks to save a widget as a template, call `save_template` with the
+          widget's HTML, a short name, description, and a description of the data shape.
+        - When a user asks to apply a template, first call `list_templates` to find the
+          right one, then call `apply_template` to get its HTML. Adapt the HTML with the
+          user's new data and render via `widgetRenderer`.
+        - When a user asks to see their templates, call `list_templates`.
+        - When a user asks to delete a template, call `delete_template`.
+        - A "save-as-template" message from the frontend means the user clicked the save
+          button on a widget. Extract the template details and call `save_template`.
     """,
 )
 

apps/agent/src/templates.py

@@ -0,0 +1,138 @@
+from langchain.tools import ToolRuntime, tool
+from langchain.messages import ToolMessage
+from langgraph.types import Command
+from typing import TypedDict
+import uuid
+from datetime import datetime
+
+
+class UITemplate(TypedDict):
+    id: str
+    name: str
+    description: str
+    html: str
+    data_description: str
+    created_at: str
+    version: int
+
+
+@tool
+def save_template(
+    name: str,
+    description: str,
+    html: str,
+    data_description: str,
+    runtime: ToolRuntime,
+) -> Command:
+    """
+    Save a generated UI as a reusable template.
+    Call this when the user wants to save a widget/visualization they liked for reuse later.
+
+    Args:
+        name: Short name for the template (e.g. "Invoice", "Dashboard")
+        description: What the template displays or does
+        html: The raw HTML string of the widget to save as a template
+        data_description: Description of the data shape this template expects
+    """
+    templates = list(runtime.state.get("templates", []))
+
+    template: UITemplate = {
+        "id": str(uuid.uuid4()),
+        "name": name,
+        "description": description,
+        "html": html,
+        "data_description": data_description,
+        "created_at": datetime.now().isoformat(),
+        "version": 1,
+    }
+    templates.append(template)
+
+    return Command(update={
+        "templates": templates,
+        "messages": [
+            ToolMessage(
+                content=f"Template '{name}' saved successfully (id: {template['id']})",
+                tool_call_id=runtime.tool_call_id,
+            )
+        ],
+    })
+
+
+@tool
+def list_templates(runtime: ToolRuntime):
+    """
+    List all saved UI templates. Returns template summaries (id, name, description, data_description).
+    """
+    templates = runtime.state.get("templates", [])
+    return [
+        {
+            "id": t["id"],
+            "name": t["name"],
+            "description": t["description"],
+            "data_description": t["data_description"],
+            "version": t["version"],
+        }
+        for t in templates
+    ]
+
+
+@tool
+def apply_template(template_id: str, runtime: ToolRuntime):
+    """
+    Retrieve a saved template's HTML so you can adapt it with new data.
+    After calling this, modify the HTML to fit the user's new data and render it via widgetRenderer.
+
+    Args:
+        template_id: The ID of the template to apply
+    """
+    templates = runtime.state.get("templates", [])
+    for t in templates:
+        if t["id"] == template_id:
+            return {
+                "name": t["name"],
+                "description": t["description"],
+                "html": t["html"],
+                "data_description": t["data_description"],
+            }
+    return {"error": f"Template with id '{template_id}' not found"}
+
+
+@tool
+def delete_template(template_id: str, runtime: ToolRuntime) -> Command:
+    """
+    Delete a saved UI template.
+
+    Args:
+        template_id: The ID of the template to delete
+    """
+    templates = list(runtime.state.get("templates", []))
+    original_len = len(templates)
+    templates = [t for t in templates if t["id"] != template_id]
+
+    if len(templates) == original_len:
+        return Command(update={
+            "messages": [
+                ToolMessage(
+                    content=f"Template with id '{template_id}' not found",
+                    tool_call_id=runtime.tool_call_id,
+                )
+            ],
+        })
+
+    return Command(update={
+        "templates": templates,
+        "messages": [
+            ToolMessage(
+                content=f"Template deleted successfully",
+                tool_call_id=runtime.tool_call_id,
+            )
+        ],
+    })
+
+
+template_tools = [
+    save_template,
+    list_templates,
+    apply_template,
+    delete_template,
+]

apps/agent/src/todos.py

@@ -5,6 +5,8 @@
 from typing import TypedDict, Literal
 import uuid
 
+from src.templates import UITemplate
+
 class Todo(TypedDict):
     id: str
     title: str
@@ -14,6 +16,7 @@ class Todo(TypedDict):
 
 class AgentState(BaseAgentState):
     todos: list[Todo]
+    templates: list[UITemplate]
 
 @tool
 def manage_todos(todos: list[Todo], runtime: ToolRuntime) -> Command:

apps/app/src/app/globals.css

@@ -621,3 +621,19 @@ body, html {
 @keyframes spin {
   to { transform: rotate(360deg); }
 }
+
+/* Template save animations */
+@keyframes tmpl-pop {
+  0%   { transform: scale(0.8); opacity: 0; }
+  50%  { transform: scale(1.05); }
+  100% { transform: scale(1); opacity: 1; }
+}
+
+@keyframes tmpl-check {
+  to { stroke-dashoffset: 0; }
+}
+
+@keyframes tmpl-slideIn {
+  from { transform: translateY(-4px) scale(0.97); opacity: 0; }
+  to   { transform: translateY(0) scale(1); opacity: 1; }
+}

apps/app/src/app/page.tsx

@@ -1,26 +1,76 @@
 "use client";
 
-import { useEffect } from "react";
+import { useEffect, useState, useCallback } from "react";
 import { ExampleLayout } from "@/components/example-layout";
 import { useGenerativeUIExamples, useExampleSuggestions } from "@/hooks";
 import { ExplainerCardsPortal } from "@/components/explainer-cards";
+import { TemplateLibrary } from "@/components/template-library";
 
 import { CopilotChat } from "@copilotkit/react-core/v2";
+import { useAgent } from "@copilotkit/react-core/v2";
 
 export default function HomePage() {
   useGenerativeUIExamples();
   useExampleSuggestions();
 
-  // Widget bridge: handle openLink from widget iframes
+  const { agent } = useAgent();
+  const [templateDrawerOpen, setTemplateDrawerOpen] = useState(false);
+
+  // Save a template directly to agent state — no chat round-trip
+  const saveTemplate = useCallback((data: {
+    name: string;
+    title: string;
+    description: string;
+    html: string;
+  }) => {
+    const templates = agent.state?.templates || [];
+    const newTemplate = {
+      id: crypto.randomUUID(),
+      name: data.name || data.title || "Untitled Template",
+      description: data.description || data.title || "",
+      html: data.html,
+      data_description: "",
+      created_at: new Date().toISOString(),
+      version: 1,
+    };
+    agent.setState({ templates: [...templates, newTemplate] });
+  }, [agent]);
+
+  // Send a prompt to the CopilotChat by finding its textarea and submitting
+  const sendPrompt = useCallback((text: string) => {
+    const input = document.querySelector<HTMLTextAreaElement>(
+      '[class*="copilot"] textarea, [data-copilotkit] textarea'
+    );
+    if (input) {
+      const setter = Object.getOwnPropertyDescriptor(
+        window.HTMLTextAreaElement.prototype,
+        "value"
+      )?.set;
+      setter?.call(input, text);
+      input.dispatchEvent(new Event("input", { bubbles: true }));
+      setTimeout(() => {
+        const form = input.closest("form");
+        if (form) {
+          form.dispatchEvent(new Event("submit", { bubbles: true, cancelable: true }));
+        }
+      }, 50);
+    }
+  }, []);
+
+  // Widget bridge: handle messages from widget iframes
   useEffect(() => {
     const handler = (e: MessageEvent) => {
       if (e.data?.type === "open-link" && typeof e.data.url === "string") {
         window.open(e.data.url, "_blank", "noopener,noreferrer");
       }
+      // Handle save-as-template from WidgetRenderer — save directly to state
+      if (e.data?.type === "save-as-template") {
+        saveTemplate(e.data);
+      }
     };
     window.addEventListener("message", handler);
     return () => window.removeEventListener("message", handler);
-  }, []);
+  }, [saveTemplate]);
 
   return (
     <>
@@ -58,19 +108,38 @@ export default function HomePage() {
                   <span className="font-normal" style={{ color: "var(--text-secondary)" }}> — powered by CopilotKit</span>
                 </p>
               </div>
-              <a
-                href="https://github.com/CopilotKit/OpenGenerativeUI"
-                target="_blank"
-                rel="noopener noreferrer"
-                className="inline-flex items-center px-5 py-2 rounded-full text-sm font-semibold text-white no-underline whitespace-nowrap transition-all duration-150 hover:-translate-y-px"
-                style={{
-                  background: "linear-gradient(135deg, var(--color-lilac-dark), var(--color-mint-dark))",
-                  boxShadow: "0 1px 4px rgba(149,153,204,0.3)",
-                  fontFamily: "var(--font-family)",
-                }}
-              >
-                Get started
-              </a>
+              <div className="flex items-center gap-2">
+                {/* Template Library toggle */}
+                <button
+                  onClick={() => setTemplateDrawerOpen(true)}
+                  className="inline-flex items-center gap-1.5 px-3 py-2 rounded-full text-sm font-medium no-underline whitespace-nowrap transition-all duration-150 hover:-translate-y-px"
+                  style={{
+                    color: "var(--text-secondary)",
+                    border: "1px solid var(--color-border-glass, rgba(0,0,0,0.1))",
+                    background: "var(--surface-primary, rgba(255,255,255,0.6))",
+                    fontFamily: "var(--font-family)",
+                  }}
+                  title="Open Template Library"
+                >
+                  <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+                    <path d="m19 21-7-4-7 4V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2v16z" />
+                  </svg>
+                  Templates
+                </button>
+                <a
+                  href="https://github.com/CopilotKit/OpenGenerativeUI"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="inline-flex items-center px-5 py-2 rounded-full text-sm font-semibold text-white no-underline whitespace-nowrap transition-all duration-150 hover:-translate-y-px"
+                  style={{
+                    background: "linear-gradient(135deg, var(--color-lilac-dark), var(--color-mint-dark))",
+                    boxShadow: "0 1px 4px rgba(149,153,204,0.3)",
+                    fontFamily: "var(--font-family)",
+                  }}
+                >
+                  Get started
+                </a>
+              </div>
             </div>
           </div>
 
@@ -84,6 +153,13 @@ export default function HomePage() {
           <ExplainerCardsPortal />
         </div>
       </div>
+
+      {/* Template Library Drawer */}
+      <TemplateLibrary
+        open={templateDrawerOpen}
+        onClose={() => setTemplateDrawerOpen(false)}
+        onSendPrompt={sendPrompt}
+      />
     </>
   );
 }