@agent-native/core 0.149.1 → 0.149.3

package/corpus/templates/slides/AGENTS.md

@@ -4,39 +4,42 @@ Slides is an agent-native deck editor. The agent creates, edits, imports,
 exports, styles, shares, and navigates decks through actions and shared SQL
 state.
 
-Detailed deck, slide-editing, image, design-system, and export workflows live in
-`.agents/skills/`.
+## Skills
+
+Read the relevant skill before deeper work:
 
-Before building common workspace or agent UI, read `agent-native-toolkit` and
-`customizing-agent-native` for the public kit and configure/eject seams.
+- `create-deck` for new decks, reference decks, workspace defaults, outlines.
+- `slide-editing` for targeted slide changes; covers fit, density, and overflow.
+- `deck-management` for organization, sharing, import/export, and metadata.
+- `slide-images` and `image-generation-via-a2a` for image work.
+- `design-systems` for per-source design-system actions.
+- `creative-context` for cross-app source reuse, pinned packs, provenance, and
+  context opt-out.
+- `analytics-data-for-decks` for delegated data requests.
 
 ## Core Rules
 
-- Store large file/blob payloads in configured file/blob storage, not SQL: no
-  base64, `data:` URLs, images, video/audio, PDFs, ZIPs, screenshots,
-  thumbnails, or replay chunks in app tables, `application_state`, `settings`,
-  or `resources`; persist URLs, ids, or handles instead.
-- Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
+- Keep large files/blobs in configured file storage, not SQL, settings, or
+  resources; persist only URLs, ids, or handles.
+- Never hardcode secrets or private/customer data; use vault/OAuth/runtime
+  configuration and fake placeholders in examples.
 - Use actions for deck lifecycle, slide edits, imports, exports, images, design
-  systems, and sharing. Do not write deck/slide rows directly.
-- In dev, call actions with `pnpm action <name>`; in production, use native
-  tools. Read the action schema if a parameter is unclear.
+  systems, and sharing. Do not write deck/slide rows directly. Read the action
+  schema if a parameter is unclear.
 - Use `view-screen` before editing when the active deck, selected slide, or
   current layout is unclear.
 - Preserve deck structure and visual consistency. Prefer focused slide edits over
   regenerating whole decks unless requested.
-- When an uploaded PPTX or PDF is being improved, import it into the target deck
-  first with `import-pptx` or `import-file --importIntoDeck true`. Treat the
-  resulting `sourceImport` metadata as the source-of-truth contract: preserve
-  slide count, order, IDs, factual copy, notes, images, and positioned objects;
-  use `update-slide` for bounded visual edits and verify with `get-deck`.
+- When improving an uploaded PPTX or PDF, import it into the target deck first.
+  Treat `sourceImport` as the source-of-truth contract: preserve slide count,
+  order, IDs, copy, notes, images, and positioned objects; verify with
+  `get-deck`.
 - A source import with `fidelity: partial` or `imagesSkipped` is not safe to
   restyle automatically. Report the exact warning rather than silently
   replacing missing content.
 - Preserve freeform objects and their `data-slide-object-id` values. They are
   absolutely positioned `.fmd-slide` children; keep generated flex/grid in
   normal flow and mint ids only for duplicates. Use styled HTML, not inline SVG.
-- Read `slide-editing` before creating slides; it covers fit, density, and overflow.
 - Follow linked design-system tokens; read `design-systems` for per-source actions.
 - Import/export actions are shortcuts, not capability limits. For exact Google
   Drive API needs, use `provider-api-catalog`, `provider-api-docs`, and
@@ -46,21 +49,24 @@ Before building common workspace or agent UI, read `agent-native-toolkit` and
   pasted URLs may need a one-time Google reconnect for Drive export. Preserve
   imported PPTX timing metadata, including by-paragraph reveals, on slide
   records.
+- For per-click reveals, use ordered 0-based animation targets and patch the
+  complete animation list with content; stale or missing targets disable
+  reveals.
 - For images, use `generate-image-api` with provenance; show results as
   `![alt](url)`.
 - Ask a sibling app's agent with a natural-language `call-agent` message by
   default. Let that specialist use its own instructions, skills, sources, and
   tools. Direct action invocation is only for an exact bounded read with a
   fully known schema; never use it as a workaround for slow or failed A2A.
-- For data requests, read `.agents/skills/analytics-data-for-decks/SKILL.md` and
-  delegate via Analytics over A2A; do not write SQL or call providers directly.
+- For data requests, read `analytics-data-for-decks` and delegate via Analytics
+  over A2A; do not write SQL or call providers directly.
 - When the user names no reference deck or design system, call
   `get-workspace-defaults` first so a bare "make a deck about X" is still on
   brand.
-- Before generation, follow `.agents/skills/creative-context/SKILL.md`: explicit
-  request/current deck, then pinned/current pack, then narrow library search.
-  Respect `contextMode: "off"`. Submit governed context through the Context tab
-  or `manage-context-membership`; reuse only its opaque clone reference.
+- Before generation, follow `creative-context`: explicit request/current deck,
+  then pinned/current pack, then narrow library search. Respect
+  `contextMode: "off"`. Submit governed context through the Context tab or
+  `manage-context-membership`; reuse only its opaque clone reference.
 
 ## Persistence Model
 
@@ -90,15 +96,7 @@ Deck data lives in SQL and all writes go through server-side actions. Read
   PPTX and have the user import it into Google Slides. Creating a native Google
   Slides file directly requires a separate Google Slides API batchUpdate path.
 
-## Skills
-
-Read the relevant skill before deeper work:
+## Source Changes
 
-- `create-deck` for new decks, reference decks, workspace defaults, outlines.
-- `slide-editing` for targeted slide changes.
-- `deck-management` for organization, sharing, import/export, and metadata.
-- `slide-images` and `image-generation-via-a2a` for image work.
-- `design-systems`, `frontend-design`, `shadcn-ui`, and `actions` as needed.
-- `creative-context` for cross-app source reuse, pinned packs, provenance, and
-  context opt-out.
-- `analytics-data-for-decks` for delegated data.
+Before building common workspace or agent UI, read `agent-native-toolkit`; read
+`customizing-agent-native` before adapting shared UI.

package/corpus/templates/slides/actions/add-deck.ts

@@ -16,6 +16,7 @@ import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
 import { notifyClients } from "../server/handlers/decks.js";
+import { assertHumanReadableDeckTitle } from "../shared/deck-title.js";
 import {
   assertDesignSystemReadable,
   assertValidAspectRatio,
@@ -50,6 +51,7 @@ export default defineAction({
     const now = new Date().toISOString();
     deck.createdAt = deck.createdAt || now;
     deck.updatedAt = now;
+    assertHumanReadableDeckTitle(deckTitle(deck));
 
     const designSystemId = deckDesignSystemId(deck);
     await assertDesignSystemReadable(designSystemId);

package/corpus/templates/slides/actions/add-slide.ts

@@ -17,6 +17,7 @@ import { normalizeSlidePadding } from "../app/lib/normalize-slide-padding.js";
 import { getDb, schema } from "../server/db/index.js";
 import { notifyClients } from "../server/handlers/decks.js";
 import { createDeckVersionSnapshot } from "../server/lib/deck-versions.js";
+import { repairGeneratedDeckTitle } from "../shared/deck-title.js";
 import { hashSlideContent } from "../shared/slide-fit.js";
 import { slideLabelFor, touchAgentSlidePresence } from "./_agent-presence.js";
 import {
@@ -308,11 +309,20 @@ export default defineAction({
         typeof position === "number"
           ? Math.max(0, Math.min(position, slides.length))
           : slides.length;
+      const shouldRepairTitle = slides.length === 0;
       slides.splice(insertIndex, 0, newSlide);
 
       const now = new Date().toISOString();
       deck.slides = slides;
       deck.updatedAt = now;
+      const currentTitle =
+        typeof row.title === "string" && row.title.trim()
+          ? row.title
+          : deck.title;
+      const repairedTitle = shouldRepairTitle
+        ? repairGeneratedDeckTitle(currentTitle, newSlide.content)
+        : null;
+      if (repairedTitle) deck.title = repairedTitle;
       deck.creativeContext =
         contextMode === "off" && existingContext
           ? existingContext
@@ -334,7 +344,11 @@ export default defineAction({
       await db.transaction(async (tx: any) => {
         await tx
           .update(schema.decks)
-          .set({ data: JSON.stringify(deck), updatedAt: now })
+          .set({
+            ...(repairedTitle ? { title: repairedTitle } : {}),
+            data: JSON.stringify(deck),
+            updatedAt: now,
+          })
           .where(eq(schema.decks.id, deckId));
         await recordGenerationCreativeContext(
           {

package/corpus/templates/slides/actions/create-deck.ts

@@ -20,6 +20,10 @@ import { notifyClients } from "../server/handlers/decks.js";
 import { createDeckVersionSnapshot } from "../server/lib/deck-versions.js";
 import { resolveDefaultDesignSystemId } from "../server/workspace-defaults.js";
 import { ASPECT_RATIO_VALUES } from "../shared/aspect-ratios.js";
+import {
+  assertHumanReadableDeckTitle,
+  repairGeneratedDeckTitle,
+} from "../shared/deck-title.js";
 import { getDeckUrl } from "./_app-url.js";
 
 const ReuseLabelSchema = z
@@ -216,6 +220,9 @@ export default defineAction({
       ...s,
       content: normalizeSlidePadding(s.content),
     }));
+    const firstSlideContent = slides[0]?.content;
+    const resolvedTitle =
+      repairGeneratedDeckTitle(title, firstSlideContent) ?? title;
 
     if (deckId) {
       if (designSystemId) {
@@ -231,6 +238,10 @@ export default defineAction({
       if (!existing[0]) {
         throw new Error(`Deck not found: ${deckId}`);
       }
+      const existingDeckTitle =
+        repairGeneratedDeckTitle(title, firstSlideContent, existing[0].title) ??
+        resolvedTitle;
+      assertHumanReadableDeckTitle(existingDeckTitle);
       await createDeckVersionSnapshot(
         {
           id: existing[0].id,
@@ -242,7 +253,7 @@ export default defineAction({
       );
       const prevData = existing[0] ? JSON.parse(existing[0].data) : {};
       const data = {
-        title,
+        title: existingDeckTitle,
         slides,
         updatedAt: now,
         aspectRatio: aspectRatio ?? prevData.aspectRatio,
@@ -252,7 +263,7 @@ export default defineAction({
       await db
         .update(schema.decks)
         .set({
-          title,
+          title: existingDeckTitle,
           data: JSON.stringify(data),
           designSystemId: designSystemId ?? existing[0]?.designSystemId ?? null,
           updatedAt: now,
@@ -271,7 +282,7 @@ export default defineAction({
       });
       return {
         id: deckId,
-        title,
+        title: existingDeckTitle,
         slideCount: slides.length,
         url: getDeckUrl(deckId),
         deepLink: deckDeepLink(deckId),
@@ -282,6 +293,7 @@ export default defineAction({
 
     const ownerEmail = getRequestUserEmail();
     if (!ownerEmail) throw new Error("no authenticated user");
+    assertHumanReadableDeckTitle(resolvedTitle);
 
     let resolvedDesignSystemId = designSystemId;
     if (resolvedDesignSystemId) {
@@ -293,7 +305,7 @@ export default defineAction({
 
     const id = `deck-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
     const data: Record<string, unknown> = {
-      title,
+      title: resolvedTitle,
       slides,
       createdAt: now,
       updatedAt: now,
@@ -303,7 +315,7 @@ export default defineAction({
     data.creativeContext = creativeContextProvenance;
     await db.insert(schema.decks).values({
       id,
-      title,
+      title: resolvedTitle,
       data: JSON.stringify(data),
       designSystemId: resolvedDesignSystemId ?? null,
       ownerEmail,
@@ -323,7 +335,7 @@ export default defineAction({
     });
     return {
       id,
-      title,
+      title: resolvedTitle,
       slideCount: slides.length,
       url: getDeckUrl(id),
       deepLink: deckDeepLink(id),

package/corpus/templates/slides/actions/get-deck-reference-context.ts

@@ -89,7 +89,7 @@ export function buildReferenceDeckContext({
 
   lines.push(
     "",
-    `These are samples, not the full deck. Call \`get-deck --id ${id}\` if you need to see how this deck handles a case the patterns above do not cover.`,
+    `These are samples, not the full deck. Call \`get-deck --id ${id} --compact false\` only if you need full slide HTML for a case the patterns above do not cover.`,
   );
 
   return truncate(lines.join("\n"), MAX_CONTEXT_CHARS);
@@ -99,7 +99,7 @@ export default defineAction({
   description:
     "Get an existing deck's visual language as a reusable pattern library so a new deck can be written in the same style. " +
     "Returns one worked HTML example per layout as `agentContext`, deliberately without the deck's slide order — the new deck's structure comes from its own content. " +
-    "Use `get-deck` when you need a specific slide's full content instead.",
+    "Use `get-deck` with compact=false when you need full slide content instead.",
   schema: z.object({
     id: z.string().describe("Deck ID to use as the reference"),
   }),

package/corpus/templates/slides/actions/get-deck.ts

@@ -4,6 +4,7 @@ import { getRequestUserEmail } from "@agent-native/core/server/request-context";
 import { resolveAccess } from "@agent-native/core/sharing";
 import { z } from "zod";
 
+import { summarizeSlideAnimationTargets } from "../server/lib/validate-slide-animations.js";
 import "../server/db/index.js"; // ensure registerShareableResource runs
 
 function stripHtml(html: string): string {
@@ -16,6 +17,39 @@ function stripHtml(html: string): string {
     .trim();
 }
 
+function compactAnimationSummary(value: unknown, content: string) {
+  if (!Array.isArray(value)) return null;
+  const targetSummaries = summarizeSlideAnimationTargets(content, value);
+  return {
+    count: value.length,
+    steps: value.map((entry, index) => {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        return { order: index + 1, valid: false };
+      }
+      const animation = entry as Record<string, unknown>;
+      const targetSummary = targetSummaries[index];
+      return {
+        order: index + 1,
+        id: typeof animation.id === "string" ? animation.id : null,
+        elementIndex:
+          typeof animation.elementIndex === "number"
+            ? animation.elementIndex
+            : null,
+        elementPath: Array.isArray(animation.elementPath)
+          ? animation.elementPath
+          : null,
+        type: typeof animation.type === "string" ? animation.type : null,
+        targetPreview: targetSummary?.targetPreview ?? null,
+        resolvedPath: targetSummary?.resolvedPath ?? null,
+        targetValid: targetSummary?.targetValid ?? false,
+        targetIssue: targetSummary
+          ? targetSummary.targetIssue
+          : "target-not-found",
+      };
+    }),
+  };
+}
+
 function deckDeepLink(deckId: string): string {
   return buildDeepLink({
     app: "slides",
@@ -26,13 +60,22 @@ function deckDeepLink(deckId: string): string {
 
 export default defineAction({
   description:
-    "Get a specific deck with all slides. Returns full deck JSON including slide content. User-visible slide numbers are 1-based and match the UI: slide 1 is the first slide. Use slideId for edits.",
+    "Get a specific deck. Pass slideId to return only that slide; targeted agent reads include full HTML by default. In-app agent calls without slideId return compact slide metadata by default; set compact=false when full deck HTML is needed. Frontend and CLI reads remain full unless compact=true. User-visible slide numbers are 1-based and match the UI: slide 1 is the first slide. Use slideId for edits.",
+  timeoutMs: 60_000,
   schema: z.object({
     id: z.string().optional().describe("Deck ID (required)"),
+    slideId: z
+      .string()
+      .optional()
+      .describe(
+        "Optional stable slide ID. When set, return only that slide for a targeted read.",
+      ),
     compact: z
       .enum(["true", "false"])
       .optional()
-      .describe("Set to 'true' for compact output (slide summaries only)"),
+      .describe(
+        "Set to 'true' for compact slide summaries, or 'false' for full slide HTML. In-app agent calls without slideId default to compact output.",
+      ),
   }),
   http: { method: "GET" },
   mcpApp: {
@@ -45,7 +88,7 @@ export default defineAction({
       height: 680,
     }),
   },
-  run: async (args) => {
+  run: async (args, ctx) => {
     if (!args.id) {
       throw new Error("--id is required.");
     }
@@ -61,8 +104,31 @@ export default defineAction({
     const data = JSON.parse(row.data);
     const slides = data?.slides || [];
     const ownerEmail = getRequestUserEmail();
+    const selectedSlideIndex =
+      args.slideId === undefined
+        ? -1
+        : slides.findIndex((slide: any) => slide?.id === args.slideId);
+
+    if (args.slideId !== undefined && selectedSlideIndex < 0) {
+      throw Object.assign(new Error(`Slide not found: ${args.slideId}`), {
+        statusCode: 404,
+      });
+    }
 
-    if (args.compact === "true") {
+    const selectedSlide =
+      selectedSlideIndex >= 0 ? slides[selectedSlideIndex] : null;
+    const slideEntries: Array<{ slide: any; index: number }> =
+      selectedSlideIndex >= 0
+        ? [{ slide: selectedSlide, index: selectedSlideIndex }]
+        : slides.map((slide: any, index: number) => ({ slide, index }));
+
+    const compact =
+      args.compact === "true" ||
+      (args.compact === undefined &&
+        ctx?.caller === "tool" &&
+        selectedSlideIndex < 0);
+
+    if (compact) {
       return {
         id: row.id,
         title: row.title || data?.title,
@@ -84,18 +150,27 @@ export default defineAction({
         slideNumbering:
           'User-visible slide numbers are 1-based and match the UI. "Slide 1" means slideNumber 1 / zeroBasedIndex 0. Use slideId for edits.',
         deepLink: deckDeepLink(row.id),
-        slides: slides.map((s: any, i: number) => ({
+        ...(selectedSlide ? { selectedSlideId: selectedSlide.id } : {}),
+        slides: slideEntries.map(({ slide: s, index: i }) => ({
           slideNumber: i + 1,
           zeroBasedIndex: i,
           id: s.id,
           layout: s.layout ?? null,
+          transition: s.transition ?? null,
+          animations: compactAnimationSummary(
+            s.animations,
+            typeof s.content === "string" ? s.content : "",
+          ),
           textPreview: stripHtml(s.content || "").slice(0, 120),
         })),
       };
     }
 
+    const deckMetadata = { ...data };
+    delete deckMetadata.slides;
+
     return {
-      ...data,
+      ...deckMetadata,
       id: row.id,
       title: row.title || data?.title,
       visibility: row.visibility,
@@ -108,7 +183,8 @@ export default defineAction({
         typeof data.createdAt === "string" ? data.createdAt : row.createdAt,
       updatedAt: row.updatedAt,
       deepLink: deckDeepLink(row.id),
-      slides: slides.map((s: any, i: number) => ({
+      ...(selectedSlide ? { selectedSlideId: selectedSlide.id } : {}),
+      slides: slideEntries.map(({ slide: s, index: i }) => ({
         ...s,
         slideNumber: i + 1,
         zeroBasedIndex: i,

package/corpus/templates/slides/actions/import-file.ts

@@ -28,6 +28,7 @@ import {
   DEFAULT_ASPECT_RATIO,
   type AspectRatio,
 } from "../shared/aspect-ratios.js";
+import { isOpaqueDeckTitle } from "../shared/deck-title.js";
 import { readUserUploadedFile } from "./_uploaded-files.js";
 import { withDeckLock } from "./patch-deck.js";
 
@@ -586,7 +587,7 @@ async function buildPptxSlide(
 
 function titleFromPath(filePath: string): string {
   const base = path.basename(filePath, path.extname(filePath)).trim();
-  return base || "Imported File";
+  return base && !isOpaqueDeckTitle(base) ? base : "Imported File";
 }
 
 function normalizePdfPages(result: unknown): { num: number; text: string }[] {