fix(templates): resolve review findings — security comment, chip fallback, seed sync, param order

- Add comment explaining why postMessage uses targetOrigin "*" (sandboxed iframe)
- Rewrite TemplateChip with useSyncExternalStore to satisfy lint rules, add
  inline fallback when CopilotKit DOM structure isn't available, document coupling
- Seed templates into agent state on first render so apply_template works when
  users ask by name in chat (not just via UI button)
- Reorder apply_template params to put runtime first, removing unsafe None default

Author: GeneralJerel

apps/agent/src/templates.py

@@ -79,7 +79,7 @@ def list_templates(runtime: ToolRuntime):
 
 
 @tool
-def apply_template(name: str = "", template_id: str = "", runtime: ToolRuntime = None):
+def apply_template(runtime: ToolRuntime, name: str = "", template_id: str = ""):
     """
     Retrieve a saved template's HTML so you can adapt it with new data.
     After calling this, generate a NEW widget in the same style and render via widgetRenderer.

apps/app/src/components/generative-ui/widget-renderer.tsx

@@ -517,6 +517,8 @@ export function WidgetRenderer({ title, description, html }: WidgetRendererProps
 
     const iframe = iframeRef.current;
     if (iframe.contentWindow) {
+      // targetOrigin "*" is required: the sandboxed iframe (allow-scripts only,
+      // no allow-same-origin) has a null origin, so no specific origin can be used.
       iframe.contentWindow.postMessage(
         { type: "update-content", html },
         "*"

apps/app/src/components/template-library/index.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { useEffect } from "react";
 import { useAgent } from "@copilotkit/react-core/v2";
 import { TemplateCard } from "./template-card";
 import { SEED_TEMPLATES } from "./seed-templates";
@@ -23,7 +24,24 @@ interface Template {
 export function TemplateLibrary({ open, onClose }: TemplateLibraryProps) {
   const { agent } = useAgent();
   const agentTemplates: Template[] = agent.state?.templates || [];
-  // Merge seed templates with user-saved ones
+
+  // Seed templates into agent state on first render so the backend can find them
+  // via apply_template even when the user asks by name in chat (no pending_template).
+  useEffect(() => {
+    const missing = SEED_TEMPLATES.filter(
+      (s) => !agentTemplates.some((t) => t.id === s.id)
+    );
+    if (missing.length > 0 && agent.state) {
+      agent.setState({
+        ...agent.state,
+        templates: [...agentTemplates, ...missing],
+      });
+    }
+    // Only run when agent state first becomes available
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [!!agent.state]);
+
+  // Merge seed templates with user-saved ones for display
   const templates: Template[] = [
     ...SEED_TEMPLATES.filter((s) => !agentTemplates.some((t) => t.id === s.id)),
     ...agentTemplates,

apps/app/src/components/template-library/template-chip.tsx

@@ -1,59 +1,87 @@
 "use client";
 
-import { useEffect, useState, useCallback } from "react";
+import { useSyncExternalStore, useEffect, useCallback } from "react";
 import { createPortal } from "react-dom";
 import { useAgent } from "@copilotkit/react-core/v2";
 
 /**
- * Renders a dismissible chip inside the CopilotChat input pill when a template
- * is attached (pending_template is set in agent state). Uses a portal to insert
- * itself inside the textarea's column container.
+ * Manages the DOM element used as the portal container for the template chip.
+ * Uses a subscribe/getSnapshot pattern compatible with useSyncExternalStore
+ * to avoid setState-in-effect and ref-during-render lint violations.
+ *
+ * COUPLING NOTE: This depends on CopilotKit's internal DOM structure —
+ * specifically that `[data-testid="copilot-chat-textarea"]` exists and sits inside
+ * a parent column div. If CopilotKit changes this structure, the chip falls back
+ * to rendering inline instead of portaling into the textarea.
  */
+let chipContainer: HTMLElement | null = null;
+const listeners = new Set<() => void>();
+
+function getChipContainer() {
+  return chipContainer;
+}
+
+function subscribeChipContainer(cb: () => void) {
+  listeners.add(cb);
+  return () => { listeners.delete(cb); };
+}
+
+function ensureChipContainer(active: boolean) {
+  if (!active) {
+    if (chipContainer) {
+      chipContainer.remove();
+      chipContainer = null;
+      listeners.forEach((cb) => cb());
+    }
+    return;
+  }
+
+  if (chipContainer) return;
+
+  const textarea = document.querySelector<HTMLElement>(
+    '[data-testid="copilot-chat-textarea"]'
+  );
+  const textareaColumn = textarea?.parentElement;
+  if (!textareaColumn) return;
+
+  let el = textareaColumn.querySelector<HTMLElement>("[data-template-chip]");
+  if (!el) {
+    el = document.createElement("div");
+    el.setAttribute("data-template-chip", "");
+    el.style.cssText = "display: flex; padding: 4px 0 0 0;";
+    textareaColumn.insertBefore(el, textarea);
+  }
+  chipContainer = el;
+  listeners.forEach((cb) => cb());
+}
+
 export function TemplateChip() {
   const { agent } = useAgent();
   const pending = agent.state?.pending_template as
     | { id: string; name: string }
     | null
     | undefined;
 
-  const [container, setContainer] = useState<HTMLElement | null>(null);
+  const container = useSyncExternalStore(subscribeChipContainer, getChipContainer, () => null);
 
   useEffect(() => {
-    if (!pending?.name) {
-      // Clean up existing container
-      document.querySelector("[data-template-chip]")?.remove();
-      setContainer(null);
-      return;
-    }
-
-    const textarea = document.querySelector<HTMLElement>(
-      '[data-testid="copilot-chat-textarea"]'
-    );
-    // The textarea sits inside a column div inside the grid
-    const textareaColumn = textarea?.parentElement;
-    if (!textareaColumn) {
-      setContainer(null);
-      return;
-    }
-
-    // Reuse existing or create chip container
-    let el = textareaColumn.querySelector<HTMLElement>("[data-template-chip]");
-    if (!el) {
-      el = document.createElement("div");
-      el.setAttribute("data-template-chip", "");
-      el.style.cssText = "display: flex; padding: 4px 0 0 0;";
-      textareaColumn.insertBefore(el, textarea);
-    }
-    setContainer(el);
+    ensureChipContainer(!!pending?.name);
   }, [pending?.name]);
 
+  // Clean up DOM node on unmount
+  useEffect(() => {
+    return () => {
+      ensureChipContainer(false);
+    };
+  }, []);
+
   const handleDismiss = useCallback(() => {
     agent.setState({ ...agent.state, pending_template: null });
   }, [agent]);
 
-  if (!pending?.name || !container) return null;
+  if (!pending?.name) return null;
 
-  return createPortal(
+  const chipContent = (
     <div
       className="inline-flex items-center gap-1.5 pl-2 pr-1 py-0.5 rounded-md text-xs font-medium select-none"
       style={{
@@ -101,7 +129,11 @@ export function TemplateChip() {
           <path d="m6 6 12 12" />
         </svg>
       </button>
-    </div>,
-    container
+    </div>
   );
+
+  // Fallback: render inline when CopilotKit DOM structure isn't available
+  if (!container) return chipContent;
+
+  return createPortal(chipContent, container);
 }