@agent-native/core 0.149.1 → 0.149.2

package/corpus/templates/slides/AGENTS.md

@@ -12,11 +12,10 @@ Before building common workspace or agent UI, read `agent-native-toolkit` and
 
 ## 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
@@ -25,11 +24,10 @@ Before building common workspace or agent UI, read `agent-native-toolkit` and
   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.
@@ -46,6 +44,9 @@ 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

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.ts

@@ -16,6 +16,31 @@ function stripHtml(html: string): string {
     .trim();
 }
 
+function compactAnimationSummary(value: unknown) {
+  if (!Array.isArray(value)) return null;
+  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>;
+      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,
+      };
+    }),
+  };
+}
+
 function deckDeepLink(deckId: string): string {
   return buildDeepLink({
     app: "slides",
@@ -26,7 +51,8 @@ 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 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. After a mutation or for a large deck when only IDs, count, previews, and animation targets are needed, pass compact=true to avoid retransmitting all slide HTML.",
+  timeoutMs: 60_000,
   schema: z.object({
     id: z.string().optional().describe("Deck ID (required)"),
     compact: z
@@ -89,6 +115,8 @@ export default defineAction({
           zeroBasedIndex: i,
           id: s.id,
           layout: s.layout ?? null,
+          transition: s.transition ?? null,
+          animations: compactAnimationSummary(s.animations),
           textPreview: stripHtml(s.content || "").slice(0, 120),
         })),
       };

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

@@ -32,6 +32,10 @@ import {
   type SourceImportMetadata,
 } from "../server/lib/source-import.js";
 import { ASPECT_RATIO_VALUES } from "../shared/aspect-ratios.js";
+import {
+  assertHumanReadableDeckTitle,
+  repairGeneratedDeckTitle,
+} from "../shared/deck-title.js";
 
 // ---------------------------------------------------------------------------
 // Per-deck write lock — same pattern as add-slide.ts so all client and agent
@@ -66,6 +70,27 @@ export function withDeckLock<T>(
 // Operation schemas
 // ---------------------------------------------------------------------------
 
+const SlideAnimationSchema = z.object({
+  id: z.string().min(1).describe("Stable ID for this ordered reveal step"),
+  elementIndex: z
+    .number()
+    .int()
+    .min(0)
+    .describe(
+      "0-based legacy child index. Keep it paired with elementPath for compatibility.",
+    ),
+  elementPath: z
+    .array(z.number().int().min(0))
+    .min(1)
+    .optional()
+    .describe(
+      "Preferred 0-based child-index path from the outer .fmd-slide wrapper. Re-read final HTML after content edits.",
+    ),
+  type: z
+    .enum(["appear", "fade", "slide-up", "zoom"])
+    .describe("Animation used when this step is revealed"),
+});
+
 const SlideFieldsSchema = z.object({
   content: z.string().optional(),
   notes: z.string().optional(),
@@ -75,8 +100,16 @@ const SlideFieldsSchema = z.object({
   imageLoading: z.boolean().optional(),
   imagePrompt: z.string().optional(),
   excalidrawData: z.string().optional(),
-  transition: z.string().optional(),
-  animations: z.array(z.unknown()).optional(),
+  transition: z
+    .enum(["instant", "none", "fade", "slide", "zoom"])
+    .optional()
+    .describe("Transition used when entering this slide"),
+  animations: z
+    .array(SlideAnimationSchema)
+    .optional()
+    .describe(
+      "Complete ordered on-click reveal list. Include every intended target in order; unlisted elements remain visible. Use elementPath from the final HTML and 0-based indexes.",
+    ),
 });
 
 /** Update fields on a single existing slide */
@@ -171,11 +204,51 @@ export function assertSourceImportOperationsPreserved(
   );
 }
 
+/**
+ * A deck-wide source restyle must be atomic from the agent's point of view:
+ * accepting a partial batch makes an apparently successful run indistinguishable
+ * from a run that quietly left the tail of the imported deck untouched.
+ */
+export function assertSourceImportSlidesCovered(
+  metadata: SourceImportMetadata | null,
+  operations: Operation[],
+  requireAllSourceSlides: boolean,
+): void {
+  if (!metadata || !requireAllSourceSlides) return;
+
+  const sourceSlideIds =
+    Array.isArray(metadata.slideIds) && metadata.slideIds.length > 0
+      ? metadata.slideIds
+      : metadata.slides.map((slide) => slide.id);
+  const patchedContentSlideIds = new Set(
+    operations.flatMap((operation) =>
+      operation.op === "patch-slide" && operation.fields.content !== undefined
+        ? [operation.slideId]
+        : [],
+    ),
+  );
+  const missingSlideIds = sourceSlideIds.filter(
+    (slideId) => !patchedContentSlideIds.has(slideId),
+  );
+  if (missingSlideIds.length === 0) return;
+
+  throw new Error(
+    `Deck-wide source restyle requires one content patch per imported slide. Missing ${missingSlideIds.length} slide(s): ${missingSlideIds.slice(0, 12).join(", ")}${missingSlideIds.length > 12 ? ", …" : ""}. Continue with every source slide ID in one patch-deck call before verifying with get-deck compact=true.`,
+  );
+}
+
 // The browser uses the full operation union above. Agents additionally use
 // this action for one bounded, deck-wide layout repair: one patch-slide per
-// slide in a single SQL transaction, followed by a fresh read for verification.
+// source slide in a single SQL transaction, followed by compact verification.
 const AgentPatchDeckInputSchema = z.object({
   deckId: z.string().describe("Deck ID"),
+  requireAllSourceSlides: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe(
+      "For a deck-wide source-import restyle, require one content patch for every imported slide before any write is committed.",
+    ),
   operations: z
     .array(
       z.union([
@@ -192,7 +265,7 @@ const AgentPatchDeckInputSchema = z.object({
     )
     .min(1)
     .describe(
-      "One patch-slide operation per slide that needs a structural HTML repair. Use patch-deck-fields only for a deck title change.",
+      "For a deck-wide source restyle, include one patch-slide operation with content for every existing source slide. Use patch-deck-fields only for a deck title change.",
     ),
 });
 
@@ -332,7 +405,19 @@ export function applyOperation(deck: any, op: Operation): void {
 
     case "patch-deck-fields": {
       const { fields } = op;
-      if (fields.title !== undefined) deck.title = fields.title;
+      if (fields.title !== undefined) {
+        const repairedTitle = repairGeneratedDeckTitle(
+          fields.title,
+          slides[0]?.content,
+          deck.title,
+        );
+        if (repairedTitle) {
+          deck.title = repairedTitle;
+        } else {
+          assertHumanReadableDeckTitle(fields.title);
+          deck.title = fields.title;
+        }
+      }
       if ("designSystemId" in fields)
         deck.designSystemId = fields.designSystemId;
       if (fields.tweaks !== undefined) deck.tweaks = fields.tweaks;
@@ -353,6 +438,7 @@ export function applyOperation(deck: any, op: Operation): void {
 export function resolveDeckColumnUpdates(
   current: { title: string; designSystemId: string | null },
   operations: Operation[],
+  resolvedTitle?: string,
 ): { title: string; designSystemId: string | null } {
   const fieldOps = operations
     .filter(
@@ -363,7 +449,7 @@ export function resolveDeckColumnUpdates(
   const titleOp = fieldOps.find((op) => typeof op.fields.title === "string");
   const dsOp = fieldOps.find((op) => "designSystemId" in op.fields);
   return {
-    title: titleOp?.fields.title ?? current.title,
+    title: resolvedTitle ?? titleOp?.fields.title ?? current.title,
     designSystemId: dsOp
       ? (dsOp.fields.designSystemId ?? null)
       : current.designSystemId,
@@ -391,10 +477,22 @@ export default defineAction({
     "Granular deck patch used by the browser editor for concurrent-safe writes. " +
     "Each operation touches only the target slide or field — concurrent writers " +
     "on different slides never overwrite each other's work. For a deck-wide " +
-    "layout repair, send one patch-slide operation per affected slide in one " +
-    "call, then call get-deck to verify the persisted HTML before reporting success.",
+    "source restyle, set requireAllSourceSlides=true and send one patch-slide " +
+    "operation with content for every imported slide in one call; the action " +
+    "rejects partial coverage. For animations, inspect the final slide HTML, " +
+    "then patch content and the complete ordered animations list together; " +
+    "validate every 0-based elementPath and do not invent one-based indexes. " +
+    "Then call get-deck with compact=true to verify the persisted slide IDs, " +
+    "count, and animation metadata before reporting success.",
   schema: z.object({
     deckId: z.string().describe("Deck ID"),
+    requireAllSourceSlides: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe(
+        "For a deck-wide source-import restyle, require one content patch for every imported slide before any write is committed.",
+      ),
     operations: z
       .array(OperationSchema)
       .min(1)
@@ -414,7 +512,10 @@ export default defineAction({
       ),
   }),
   agentInputSchema: AgentPatchDeckInputSchema,
-  run: async ({ deckId, operations, creativeContext }, ctx) => {
+  run: async (
+    { deckId, operations, requireAllSourceSlides, creativeContext },
+    ctx,
+  ) => {
     await assertAccess("deck", deckId, "editor");
     const isAgentCaller = isAgentPatchCaller(ctx?.caller);
 
@@ -450,6 +551,11 @@ export default defineAction({
       const sourceImport = sourceImportForDeck(deck.sourceImport);
       if (isAgentCaller) {
         assertSourceImportOperationsPreserved(sourceImport, operations);
+        assertSourceImportSlidesCovered(
+          sourceImport,
+          operations,
+          requireAllSourceSlides,
+        );
       }
       for (const op of operations) {
         if (
@@ -482,6 +588,13 @@ export default defineAction({
         resolveDeckColumnUpdates(
           { title: row.title, designSystemId: row.designSystemId },
           operations,
+          operations.some(
+            (operation) =>
+              operation.op === "patch-deck-fields" &&
+              operation.fields.title !== undefined,
+          ) && typeof deck.title === "string"
+            ? deck.title
+            : undefined,
         );
 
       let generationRecord:

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

@@ -19,6 +19,10 @@ import { z } from "zod";
 import { getDb, schema } from "../server/db/index.js";
 import { notifyClients } from "../server/handlers/decks.js";
 import { createDeckVersionSnapshot } from "../server/lib/deck-versions.js";
+import {
+  assertHumanReadableDeckTitle,
+  repairGeneratedDeckTitle,
+} from "../shared/deck-title.js";
 import {
   assertDesignSystemReadable,
   assertValidAspectRatio,
@@ -71,7 +75,7 @@ export default defineAction({
 
       deck.id = deckId;
       deck.updatedAt = now;
-      const title = deckTitle(deck);
+      const requestedTitle = deckTitle(deck);
       const nextDesignSystemId = deckDesignSystemId(deck);
 
       // Resolve access first — this loads the row AND tells us the caller's
@@ -88,6 +92,11 @@ export default defineAction({
         if (!ownerEmail) {
           throw deckHttpError(403, "Sign in to create a deck");
         }
+        const title =
+          repairGeneratedDeckTitle(requestedTitle, firstSlideContent(deck)) ??
+          requestedTitle;
+        assertHumanReadableDeckTitle(title);
+        deck.title = title;
         await assertDesignSystemReadable(nextDesignSystemId);
         try {
           await db.insert(schema.decks).values({
@@ -110,6 +119,14 @@ export default defineAction({
         access.role === "admin" ||
         access.role === "editor"
       ) {
+        const title =
+          repairGeneratedDeckTitle(
+            requestedTitle,
+            firstSlideContent(deck),
+            access.resource.title,
+          ) ?? requestedTitle;
+        assertHumanReadableDeckTitle(title);
+        deck.title = title;
         await assertDesignSystemReadable(nextDesignSystemId);
         if (shouldSnapshotDeckWrite(access.resource, title, deck)) {
           await createDeckVersionSnapshot(
@@ -142,3 +159,9 @@ export default defineAction({
       return deck;
     }),
 });
+
+function firstSlideContent(deck: DeckPayload): string | null {
+  const slides = Array.isArray(deck.slides) ? deck.slides : [];
+  const content = slides[0] && (slides[0] as Record<string, unknown>).content;
+  return typeof content === "string" ? content : null;
+}