@agent-native/core 0.137.2 → 0.137.4

package/corpus/templates/slides/app/components/layout/Sidebar.tsx

@@ -286,7 +286,6 @@ export function Sidebar({ collapsed, onToggleCollapsed }: SidebarProps) {
             feedback={feedbackButton}
             search={searchButton}
             collapse={collapseButton}
-            className="px-0 py-0"
           />
         </div>
       </div>

package/corpus/templates/slides/app/hooks/use-deck-design-system.ts

@@ -1,6 +1,9 @@
 import { useActionQuery } from "@agent-native/core/client/hooks";
 
-import type { DesignSystemData } from "../../shared/api";
+import {
+  normalizeReferenceUrls,
+  type DesignSystemData,
+} from "../../shared/api";
 
 const DEFAULT_DESIGN_SYSTEM: DesignSystemData = {
   colors: {
@@ -54,10 +57,23 @@ function mergeWithDefaults<T>(defaults: T, value: unknown): T {
   return (value === undefined || value === null ? defaults : value) as T;
 }
 
+export function getDesignSystemImageStyleReferenceUrls(
+  designSystem?: Pick<DesignSystemData, "imageStyle"> | null,
+): string[] {
+  return normalizeReferenceUrls(designSystem?.imageStyle?.referenceUrls);
+}
+
 export function mergeDesignSystemData(value: unknown): DesignSystemData {
   return mergeWithDefaults(DEFAULT_DESIGN_SYSTEM, value);
 }
 
+export interface DeckDesignSystemResult {
+  designSystem: DesignSystemData;
+  designSystemTitle: string | null;
+  imageStyleReferenceUrls: string[];
+  isLoading: boolean;
+}
+
 export function useDeckDesignSystem(designSystemId?: string | null) {
   const { data, isLoading } = useActionQuery<{
     id: string;
@@ -71,6 +87,7 @@ export function useDeckDesignSystem(designSystemId?: string | null) {
     return {
       designSystem: DEFAULT_DESIGN_SYSTEM,
       designSystemTitle: null,
+      imageStyleReferenceUrls: [],
       isLoading: false,
     };
   }
@@ -80,12 +97,14 @@ export function useDeckDesignSystem(designSystemId?: string | null) {
     return {
       designSystem: parsed,
       designSystemTitle: data.title ?? null,
+      imageStyleReferenceUrls: getDesignSystemImageStyleReferenceUrls(parsed),
       isLoading,
     };
   } catch {
     return {
       designSystem: DEFAULT_DESIGN_SYSTEM,
       designSystemTitle: data.title ?? null,
+      imageStyleReferenceUrls: [],
       isLoading,
     };
   }

package/corpus/templates/slides/app/i18n/en-US.ts

@@ -670,6 +670,21 @@ const messages = {
     referenceDeckNone: "Don't use one",
     referenceDeckStarredGroup: "Starred",
     referenceDeckOtherGroup: "Other decks",
+    referenceReviewTitle: "Review references",
+    referenceReviewDescription:
+      "Keep the default design system and reference deck unless you remove them. Search for another deck, import a file, or continue when you're ready.",
+    chooseAnotherDeck: "Choose another deck",
+    noMatchingDecks: "No matching decks found.",
+    googleSlidesReferenceTitle: "Google Slides",
+    googleSlidesReferenceConnect:
+      "Connect Google Drive to import a Slides deck.",
+    googleSlidesReferenceChoose: "Choose Google Slides deck",
+    googleSlidesReferencePicking: "Working...",
+    googleSlidesReferenceConnected:
+      "Connected. Choose a Google Slides deck to import as a reusable reference.",
+    googleSlidesReferenceUnavailable:
+      "Connect Google Drive and configure Picker to import a Google Slides deck.",
+    skipReferences: "Skip references",
     workspaceDefaultBadge: "Workspace default",
     setWorkspaceDefault: "Set as workspace default",
     clearWorkspaceDefault: "Clear workspace default",

package/corpus/templates/slides/app/lib/new-deck-reference-selection.ts

@@ -0,0 +1,22 @@
+export interface NewDeckReferenceSelection {
+  designSystemId: string | null;
+  referenceDeckId: string | null;
+}
+
+export function resolveNewDeckReferenceSelection(args: {
+  designSystemAuto: boolean;
+  selectedDesignSystemId: string | null;
+  defaultDesignSystemId: string | null;
+  referenceDeckAuto: boolean;
+  selectedReferenceDeckId: string | null;
+  defaultReferenceDeckId: string | null;
+}): NewDeckReferenceSelection {
+  return {
+    designSystemId: args.designSystemAuto
+      ? args.defaultDesignSystemId
+      : args.selectedDesignSystemId,
+    referenceDeckId: args.referenceDeckAuto
+      ? args.defaultReferenceDeckId
+      : args.selectedReferenceDeckId,
+  };
+}

package/corpus/templates/slides/app/pages/DeckEditor.tsx

@@ -286,7 +286,9 @@ export default function DeckEditor() {
     isNewDeckCreation: wasNewDeckCreation.current,
     slideCount,
   });
-  const { designSystem } = useDeckDesignSystem(deck?.designSystemId);
+  const { designSystem, imageStyleReferenceUrls } = useDeckDesignSystem(
+    deck?.designSystemId,
+  );
   const commentsOpen = sidePanel === "comments";
 
   const {
@@ -1313,6 +1315,7 @@ export default function DeckEditor() {
         open={imageGenOpen}
         onOpenChange={setImageGenOpen}
         anchorRef={imageGenButtonRef}
+        referenceImageUrls={imageStyleReferenceUrls}
         slideContext={
           currentSlide
             ? {

package/corpus/templates/slides/app/pages/Index.tsx

@@ -20,10 +20,7 @@ import { useLocation, useNavigate, useSearchParams } from "react-router";
 import { toast } from "sonner";
 
 import DeckCard from "@/components/deck/DeckCard";
-import {
-  NewDeckReferenceStep,
-  type NewDeckReferenceSelection,
-} from "@/components/editor/NewDeckReferenceStep";
+import { NewDeckReferenceStep } from "@/components/editor/NewDeckReferenceStep";
 import PromptPopover, {
   uploadPromptFiles,
   type UploadedFile,
@@ -48,10 +45,10 @@ import { useWorkspaceDefaults } from "@/hooks/use-workspace-defaults";
 import { createDeckAgentMessage } from "@/lib/agent-visible-message";
 import { savePromptToComposerDraft } from "@/lib/composer-draft";
 import {
-  readRecentReferences,
-  rememberRecentReference,
-  type RecentReference,
-} from "@/lib/recent-references";
+  resolveNewDeckReferenceSelection,
+  type NewDeckReferenceSelection,
+} from "@/lib/new-deck-reference-selection";
+import { rememberRecentReference } from "@/lib/recent-references";
 
 const NEW_DECK_DRAFT_SCOPE = "slides-new-deck";
 const PENDING_PROMPT_KEY = "slides:pending-deck-prompt";
@@ -239,18 +236,19 @@ export default function Index() {
   } | null>(null);
   const [showNewDeckReferenceStep, setShowNewDeckReferenceStep] =
     useState(false);
-  const [recentReferences, setRecentReferences] = useState<RecentReference[]>(
-    [],
-  );
   const [referenceImporting, setReferenceImporting] = useState(false);
   const initialPromptConsumedRef = useRef(false);
   const [signInPromptHadFiles, setSignInPromptHadFiles] = useState(false);
-  const [selectedDesignSystemId, setSelectedDesignSystemId] = useState("");
-  const [selectedReferenceDeckId, setSelectedReferenceDeckId] = useState("");
+  const [selectedDesignSystemId, setSelectedDesignSystemId] = useState<
+    string | null
+  >(null);
+  const [selectedReferenceDeckId, setSelectedReferenceDeckId] = useState<
+    string | null
+  >(null);
   // True while the picker still reflects an auto-applied default rather than
   // an explicit user choice. `useWorkspaceDefaults()`/`useDesignSystems()`
   // resolve asynchronously, so the initial value set on dialog open can be a
-  // placeholder ("none", or the first-loaded design system) — these stay
+  // placeholder ("none", or the first-loaded design system) - these stay
   // true so the hydration effects below can overwrite it once the real
   // default arrives, and flip to false the moment the user picks explicitly.
   const designSystemAutoRef = useRef(true);
@@ -293,18 +291,11 @@ export default function Index() {
     [deckFilter, decks],
   );
   const rememberReference = useCallback(
-    (reference: Omit<RecentReference, "lastUsedAt">) => {
-      const result = rememberRecentReference(reference);
-      if (result.readable) setRecentReferences(result.items);
-    },
+    (reference: Parameters<typeof rememberRecentReference>[0]) =>
+      rememberRecentReference(reference),
     [],
   );
 
-  useEffect(() => {
-    const result = readRecentReferences();
-    if (result.readable) setRecentReferences(result.items);
-  }, []);
-
   useEffect(() => {
     if (initialDesignSystemId) {
       rememberReference({
@@ -322,6 +313,10 @@ export default function Index() {
     if (!initialPrompt || initialPromptConsumedRef.current) return;
     initialPromptConsumedRef.current = true;
     setPendingDeck({ prompt: initialPrompt, files: [] });
+    designSystemAutoRef.current = true;
+    referenceDeckAutoRef.current = true;
+    setSelectedDesignSystemId(initialDesignSystemId ?? null);
+    setSelectedReferenceDeckId(workspaceReferenceDeckId ?? null);
     setShowNewDeckReferenceStep(true);
     setSearchParams(
       (previous) => {
@@ -377,8 +372,8 @@ export default function Index() {
       anchorElRef.current = e.currentTarget;
       designSystemAutoRef.current = true;
       referenceDeckAutoRef.current = true;
-      setSelectedDesignSystemId(initialDesignSystemId ?? "");
-      setSelectedReferenceDeckId(workspaceReferenceDeckId ?? "none");
+      setSelectedDesignSystemId(initialDesignSystemId ?? null);
+      setSelectedReferenceDeckId(workspaceReferenceDeckId ?? null);
       setShowNewDeckPrompt(true);
     },
     [initialDesignSystemId, workspaceReferenceDeckId],
@@ -388,12 +383,10 @@ export default function Index() {
     (open: boolean, options: { clearInitialPrompt?: boolean } = {}) => {
       setShowNewDeckPrompt(open);
       if (!open) {
-        setSelectedDesignSystemId("");
         if (options.clearInitialPrompt !== false) {
           setNewDeckInitialPrompt(null);
           setNewDeckRetryFiles([]);
         }
-        setSelectedReferenceDeckId("none");
       }
     },
     [],
@@ -424,15 +417,15 @@ export default function Index() {
   // `useWorkspaceDefaults()` and `useDesignSystems()` load asynchronously and
   // can settle in either order, so `initialDesignSystemId` may go from a
   // provisional value to the real one after the picker already has a
-  // selection — guarding on `designSystemAutoRef` (instead of on whether
+  // selection - guarding on `designSystemAutoRef` (instead of on whether
   // `selectedDesignSystemId` is already set) lets that later value win as
   // long as the user hasn't explicitly chosen something.
   useEffect(() => {
     if (!showNewDeckPrompt || !designSystemAutoRef.current) return;
     if (initialDesignSystemId) {
       setSelectedDesignSystemId(initialDesignSystemId);
-    } else if (designSystems.length > 0) {
-      setSelectedDesignSystemId("none");
+    } else {
+      setSelectedDesignSystemId(null);
     }
   }, [initialDesignSystemId, designSystems.length, showNewDeckPrompt]);
 
@@ -441,7 +434,7 @@ export default function Index() {
   // resolves unless the user already picked a reference deck.
   useEffect(() => {
     if (!showNewDeckPrompt || !referenceDeckAutoRef.current) return;
-    setSelectedReferenceDeckId(workspaceReferenceDeckId ?? "none");
+    setSelectedReferenceDeckId(workspaceReferenceDeckId ?? null);
   }, [workspaceReferenceDeckId, showNewDeckPrompt]);
 
   // Restore a prompt that was held back when the user wasn't signed in:
@@ -465,8 +458,8 @@ export default function Index() {
     }
     designSystemAutoRef.current = true;
     referenceDeckAutoRef.current = true;
-    setSelectedDesignSystemId(initialDesignSystemId ?? "none");
-    setSelectedReferenceDeckId(workspaceReferenceDeckId ?? "none");
+    setSelectedDesignSystemId(initialDesignSystemId ?? null);
+    setSelectedReferenceDeckId(workspaceReferenceDeckId ?? null);
     setShowNewDeckPrompt(true);
   }, [initialDesignSystemId, workspaceReferenceDeckId, session]);
 
@@ -490,10 +483,9 @@ export default function Index() {
   }, [location.state, navigate]);
 
   const handleCreateDeckBlank = () => {
-    const selectedDesignSystem =
-      selectedDesignSystemId && selectedDesignSystemId !== "none"
-        ? designSystems.find((ds) => ds.id === selectedDesignSystemId)
-        : undefined;
+    const selectedDesignSystem = selectedDesignSystemId
+      ? designSystems.find((ds) => ds.id === selectedDesignSystemId)
+      : undefined;
     let deck: ReturnType<typeof createDeck> | undefined;
     flushSync(() => {
       deck = createDeck(undefined, {
@@ -507,7 +499,7 @@ export default function Index() {
   const handleCreateDeckWithPrompt = async (
     prompt: string,
     files: UploadedFile[],
-    referenceSelection: NewDeckReferenceSelection = {},
+    referenceSelection: Partial<NewDeckReferenceSelection> = {},
   ) => {
     // Pre-flight auth check. The add-deck action returns 403 silently
     // when unauthenticated, leaving the user stuck on a deck page that
@@ -523,18 +515,22 @@ export default function Index() {
       newDeckRetryFiles,
       files,
     );
+    const resolvedSelection = resolveNewDeckReferenceSelection({
+      designSystemAuto: designSystemAutoRef.current,
+      selectedDesignSystemId,
+      defaultDesignSystemId: initialDesignSystemId,
+      referenceDeckAuto: referenceDeckAutoRef.current,
+      selectedReferenceDeckId,
+      defaultReferenceDeckId: workspaceReferenceDeckId,
+    });
     const designSystemId =
       referenceSelection.designSystemId !== undefined
         ? referenceSelection.designSystemId
-        : selectedDesignSystemId && selectedDesignSystemId !== "none"
-          ? selectedDesignSystemId
-          : null;
+        : resolvedSelection.designSystemId;
     const referenceDeckId =
       referenceSelection.referenceDeckId !== undefined
         ? referenceSelection.referenceDeckId
-        : selectedReferenceDeckId && selectedReferenceDeckId !== "none"
-          ? selectedReferenceDeckId
-          : null;
+        : resolvedSelection.referenceDeckId;
     const selectedDesignSystem = designSystemId
       ? designSystems.find((ds) => ds.id === designSystemId)
       : undefined;
@@ -651,30 +647,64 @@ export default function Index() {
     [setNewDeckPromptOpen],
   );
 
-  const handleReferenceSelect = useCallback(
-    async (selection: NewDeckReferenceSelection) => {
-      const pending = pendingDeck;
-      if (!pending) return;
-      if (selection.designSystemId) {
-        rememberReference({
-          id: selection.designSystemId,
-          kind: "design-system",
-        });
+  const handleReferenceDesignSystemSelect = useCallback(
+    (designSystemId: string | null) => {
+      designSystemAutoRef.current = false;
+      setSelectedDesignSystemId(designSystemId);
+      if (designSystemId) {
+        rememberReference({ id: designSystemId, kind: "design-system" });
       }
-      if (selection.referenceDeckId) {
-        rememberReference({ id: selection.referenceDeckId, kind: "deck" });
+    },
+    [rememberReference],
+  );
+
+  const handleReferenceDeckSelect = useCallback(
+    (referenceDeckId: string | null) => {
+      referenceDeckAutoRef.current = false;
+      setSelectedReferenceDeckId(referenceDeckId);
+      if (referenceDeckId) {
+        rememberReference({ id: referenceDeckId, kind: "deck" });
       }
-      setShowNewDeckReferenceStep(false);
-      setPendingDeck(null);
-      await handleCreateDeckWithPrompt(
-        pending.prompt,
-        pending.files,
-        selection,
-      );
     },
-    [handleCreateDeckWithPrompt, pendingDeck, rememberReference],
+    [rememberReference],
+  );
+
+  const handleGoogleSlidesImported = useCallback(
+    async ({ id, title }: { id: string; title: string }) => {
+      await reloadDecks();
+      rememberReference({ id, kind: "deck" });
+      referenceDeckAutoRef.current = false;
+      setSelectedReferenceDeckId(id);
+      toast.success(t("editorToolbar.importComplete"), {
+        description: title,
+      });
+    },
+    [reloadDecks, rememberReference, t],
   );
 
+  const handleReferenceContinue = useCallback(() => {
+    const pending = pendingDeck;
+    if (!pending) return;
+    setShowNewDeckReferenceStep(false);
+    setPendingDeck(null);
+    const selection = resolveNewDeckReferenceSelection({
+      designSystemAuto: designSystemAutoRef.current,
+      selectedDesignSystemId,
+      defaultDesignSystemId: initialDesignSystemId,
+      referenceDeckAuto: referenceDeckAutoRef.current,
+      selectedReferenceDeckId,
+      defaultReferenceDeckId: workspaceReferenceDeckId,
+    });
+    void handleCreateDeckWithPrompt(pending.prompt, pending.files, selection);
+  }, [
+    handleCreateDeckWithPrompt,
+    initialDesignSystemId,
+    pendingDeck,
+    selectedDesignSystemId,
+    selectedReferenceDeckId,
+    workspaceReferenceDeckId,
+  ]);
+
   const handleReferenceImport = useCallback(
     async (files: File[]) => {
       const pending = pendingDeck;
@@ -685,8 +715,9 @@ export default function Index() {
         const pptxReference = uploaded.find((file) =>
           file.originalName.toLowerCase().endsWith(".pptx"),
         );
-        let referenceSelection: NewDeckReferenceSelection = {};
-        let generationFiles = uploaded;
+        const pdfReference = uploaded.find((file) =>
+          file.originalName.toLowerCase().endsWith(".pdf"),
+        );
         if (pptxReference) {
           const imported = (await callAction("import-pptx", {
             filePath: pptxReference.path,
@@ -696,19 +727,57 @@ export default function Index() {
           }
           await reloadDecks();
           rememberReference({ id: imported.id, kind: "deck" });
-          referenceSelection = {
-            designSystemId: null,
-            referenceDeckId: imported.id,
-          };
-          generationFiles = uploaded.filter((file) => file !== pptxReference);
+          referenceDeckAutoRef.current = false;
+          setSelectedReferenceDeckId(imported.id);
         }
-        setShowNewDeckReferenceStep(false);
-        setPendingDeck(null);
-        await handleCreateDeckWithPrompt(
-          pending.prompt,
-          [...pending.files, ...generationFiles],
-          referenceSelection,
+        if (!pptxReference && pdfReference) {
+          const referenceDeck = createDeck(undefined, {
+            noDefaultSlides: true,
+          });
+          const persisted = await ensureDeckPersisted(referenceDeck.id);
+          if (!persisted) {
+            deleteDeck(referenceDeck.id);
+            throw new Error("The PDF reference deck could not be saved.");
+          }
+          try {
+            const imported = (await callAction("import-file", {
+              filePath: pdfReference.path,
+              format: "pdf",
+              deckId: referenceDeck.id,
+              importIntoDeck: true,
+            })) as { imported?: unknown; deckId?: unknown };
+            if (
+              imported.imported !== true ||
+              imported.deckId !== referenceDeck.id
+            ) {
+              throw new Error("The PDF reference deck could not be imported.");
+            }
+            await reloadDecks();
+            rememberReference({ id: referenceDeck.id, kind: "deck" });
+            referenceDeckAutoRef.current = false;
+            setSelectedReferenceDeckId(referenceDeck.id);
+          } catch (error) {
+            deleteDeck(referenceDeck.id);
+            throw error;
+          }
+        }
+        const importedReference = pptxReference ?? pdfReference;
+        const generationFiles = uploaded.filter(
+          (file) => file !== importedReference,
         );
+        if (generationFiles.length > 0) {
+          setPendingDeck((current) =>
+            current
+              ? {
+                  ...current,
+                  files: mergeUploadedFilesForRetry(
+                    current.files,
+                    generationFiles,
+                  ),
+                }
+              : current,
+          );
+        }
       } catch (error) {
         toast.error(t("editorToolbar.uploadFailed"), {
           description:
@@ -722,7 +791,9 @@ export default function Index() {
     },
     [
       callAction,
-      handleCreateDeckWithPrompt,
+      createDeck,
+      deleteDeck,
+      ensureDeckPersisted,
       pendingDeck,
       reloadDecks,
       rememberReference,
@@ -769,7 +840,7 @@ export default function Index() {
     async (deck: Deck) => {
       try {
         // A private deck is unreadable to everyone else, so share it through
-        // the audited sharing action first — it owns org binding and collab
+        // the audited sharing action first - it owns org binding and collab
         // cache invalidation, which a direct visibility write here would skip.
         if (deck.visibility === "private") {
           await callAction("set-resource-visibility", {
@@ -1080,27 +1151,43 @@ export default function Index() {
         decks={decks}
         defaultDesignSystemId={initialDesignSystemId}
         defaultReferenceDeckId={workspaceReferenceDeckId}
-        recentReferences={recentReferences}
-        onSelect={(selection) => void handleReferenceSelect(selection)}
+        selectedDesignSystemId={selectedDesignSystemId}
+        selectedReferenceDeckId={selectedReferenceDeckId}
+        onSelectDesignSystem={handleReferenceDesignSystemSelect}
+        onSelectReferenceDeck={handleReferenceDeckSelect}
         onImport={handleReferenceImport}
+        onGoogleSlidesImported={handleGoogleSlidesImported}
+        onContinue={handleReferenceContinue}
         onSkip={handleReferenceSkip}
         importing={referenceImporting}
-        title={t("home.newDeckPromptTitle")}
-        description={t("home.referenceDeckPlaceholder")}
+        title={t("home.referenceReviewTitle")}
+        description={t("home.referenceReviewDescription")}
         designSystemLabel={t("home.designSystem")}
         referenceDeckLabel={t("home.referenceDeck")}
-        chooseDeckLabel={t("home.referenceDeckPlaceholder")}
+        noneLabel={t("home.none")}
         importFileLabel={t("editorToolbar.importFile")}
         importingLabel={t("editorToolbar.importing")}
-        skipLabel={t("home.referenceDeckNone")}
+        continueLabel={t("designSystemSetup.continueToGeneration")}
+        skipLabel={t("home.skipReferences")}
         defaultSuffix={t("home.defaultSuffix")}
         starredLabel={t("home.referenceDeckStarredGroup")}
         otherDecksLabel={t("home.referenceDeckOtherGroup")}
+        searchDecksLabel={t("root.searchDecks")}
+        chooseAnotherDeckLabel={t("home.chooseAnotherDeck")}
+        noMatchingDecksLabel={t("home.noMatchingDecks")}
+        googleSlidesTitle={t("home.googleSlidesReferenceTitle")}
+        googleSlidesConnectLabel={t("home.googleSlidesReferenceConnect")}
+        googleSlidesChooseLabel={t("home.googleSlidesReferenceChoose")}
+        googleSlidesPickingLabel={t("home.googleSlidesReferencePicking")}
+        googleSlidesConnectedLabel={t("home.googleSlidesReferenceConnected")}
+        googleSlidesUnavailableLabel={t(
+          "home.googleSlidesReferenceUnavailable",
+        )}
         promptNote={pendingDeck?.prompt}
       />
 
       {/* Sign-in required to create a deck. Shown when an unauthenticated
-          user submits a prompt — the typed prompt is preserved in
+          user submits a prompt - the typed prompt is preserved in
           sessionStorage and replayed into the composer after sign-in. */}
       <AlertDialog open={showSignInDialog} onOpenChange={setSignInDialogOpen}>
         <AlertDialogContent>

package/corpus/templates/slides/server/lib/assets-image-delegation.ts

@@ -10,6 +10,8 @@ import {
   type Task,
 } from "@agent-native/core/a2a";
 
+import { normalizeReferenceUrls } from "../../shared/api.js";
+
 /**
  * Slides never calls an image-generation API itself when the Assets app is
  * reachable: Assets owns brand libraries, presets, provenance, and the
@@ -92,7 +94,7 @@ function buildDelegationMessage(request: AssetsImageRequest): string {
     );
   }
 
-  const references = request.referenceImageUrls?.filter(Boolean) ?? [];
+  const references = normalizeReferenceUrls(request.referenceImageUrls);
 
   return (
     `Generate ${request.count ?? 1} brand-consistent image candidate(s) ` +
@@ -101,7 +103,7 @@ function buildDelegationMessage(request: AssetsImageRequest): string {
     `Aspect ratio: ${request.aspectRatio ?? "16:9"}\n` +
     (hints.length ? `Slide context: ${hints.join(", ")}\n` : "") +
     (references.length
-      ? `Condition the generation on these style reference images: ` +
+      ? `Condition the generation on these referenceImageUrls: ` +
         `${references.join(", ")}\n`
       : "") +
     `\nPick the best matching library via match-library if no libraryId is ` +

package/corpus/templates/slides/shared/api.ts

@@ -10,6 +10,19 @@ export interface DemoResponse {
 
 export const DEFAULT_STYLE_REFERENCE_URLS: string[] = [];
 
+export function normalizeReferenceUrls(
+  urls: readonly string[] | null | undefined,
+): string[] {
+  const normalized: string[] = [];
+  for (const url of urls ?? []) {
+    if (typeof url !== "string") continue;
+    const trimmed = url.trim();
+    if (!trimmed || normalized.includes(trimmed)) continue;
+    normalized.push(trimmed);
+  }
+  return normalized;
+}
+
 // --- Image Generation ---
 
 export type ImageGenModel = "gemini" | "openai" | "auto";
@@ -155,7 +168,7 @@ function normalizeSlideAnimation(
     : "slide-up";
 
   // When an explicit `elementIndex` is present, trust it. Otherwise derive
-  // from the last segment of `elementPath` — keeps the index correlated
+  // from the last segment of `elementPath` - keeps the index correlated
   // with the path's actual leaf so consumers that fall back to
   // `elementIndex` target the right element instead of silently defaulting
   // to slide-element 0 (which created an ambiguity between 'animation

package/corpus/templates/tasks/.agents/skills/agent-native-toolkit/SKILL.md

@@ -32,6 +32,39 @@ Move behavior into shared toolkit primitives when it is:
 Keep behavior app-local when the abstraction would hide important domain
 language or make a simple app-specific workflow harder to understand.
 
+## Agent Surface Contract
+
+The repeated app shell has two distinct navigation surfaces:
+
+- The left rail owns domain destinations, settings, and chat history when the
+  app has a full-page chat route. Do not label a domain workflow as `Chat` just
+  because the app was scaffolded from the chat template.
+- The right `AgentSidebar` owns contextual agent work. Domain buttons that call
+  `sendToAgentChat` should open it (`openSidebar: true`) so the user can see,
+  steer, and review the agent without losing the page they were using.
+- Keep `/` or `/chat/*` as the full-page chat surface when the starter provides
+  one. Put domain workflows on named routes and wire the shell's route checks,
+  navigation labels, and handoffs to those routes together.
+- Use familiar message or neutral action icons for agent affordances. Never use
+  sparkle, wand, magic, or robot icons as an AI label; the copy should carry the
+  meaning.
+- Give the right rail a quiet visual boundary with a subtle surface shift,
+  divider, or both. The domain page and AgentSidebar should not collapse into a
+  single undifferentiated background.
+- Any button labeled as agent work must use `sendToAgentChat` with bounded
+  context and `openSidebar: true`; local deterministic analysis should be
+  labeled as local, preview, or analyze. For original/generated review, stack
+  the source above the result by default and use side-by-side only for short,
+  highly scannable content.
+- Standalone apps with `AgentSidebar` must resolve one assistant-ui runtime
+  context. Match direct assistant-ui pins to the installed core/toolkit peer
+  graph, use Vite dedupe/aliases when linked dependencies can split contexts,
+  and verify an AI handoff produces no stale-index console error.
+
+Contextual agent UI is not a reason to expose every option at once. Start with
+the domain task's primary action, reveal review or configuration only when the
+current state needs it, and let the sidebar carry conversational depth.
+
 ## Discover Before Building
 
 Before creating an app-local version of repeated workspace or agent UI: