@agent-native/core 0.149.4 → 0.149.6

package/corpus/templates/content/app/hooks/use-documents.ts

@@ -1,4 +1,5 @@
 import {
+  callAction,
   useActionQuery,
   useActionMutation,
 } from "@agent-native/core/client/hooks";
@@ -7,6 +8,7 @@ import type {
   ContentDatabaseItem,
   Document,
   DocumentCreateRequest,
+  DocumentListResponse,
   DocumentPropertiesResponse,
   DocumentUpdateRequest,
   DocumentUpdateResponse,
@@ -15,7 +17,7 @@ import type {
   DocumentTreeNode,
 } from "@shared/api";
 import type { QueryClient } from "@tanstack/react-query";
-import { useQueryClient } from "@tanstack/react-query";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { toast } from "sonner";
 
 import type { DocumentUpdateConflictResponse } from "../../actions/update-document";
@@ -63,6 +65,74 @@ export const LIST_DOCUMENTS_QUERY_KEY = [
   undefined,
 ] as const;
 
+const DOCUMENT_LIST_PAGE_SIZE = 200;
+
+export async function fetchCompleteDocumentList(
+  fetchPage: (offset: number, limit: number) => Promise<DocumentListResponse>,
+) {
+  const documents: Document[] = [];
+  const documentIds = new Set<string>();
+  let offset = 0;
+  let expectedTotal: number | null = null;
+
+  while (true) {
+    const page = await fetchPage(offset, DOCUMENT_LIST_PAGE_SIZE);
+    const { pagination } = page;
+    if (!pagination) {
+      throw new Error(
+        "list-documents returned no pagination boundary; refusing to treat the result as complete.",
+      );
+    }
+    if (
+      pagination.offset !== offset ||
+      pagination.limit !== DOCUMENT_LIST_PAGE_SIZE ||
+      pagination.returnedItems !== page.documents.length
+    ) {
+      throw new Error(
+        "list-documents returned inconsistent pagination metadata; retry the complete read.",
+      );
+    }
+    if (expectedTotal === null) expectedTotal = pagination.totalItems;
+    if (pagination.totalItems !== expectedTotal) {
+      throw new Error(
+        "Documents changed during paginated discovery; retry the complete read.",
+      );
+    }
+    for (const document of page.documents) {
+      if (documentIds.has(document.id)) {
+        throw new Error(
+          `list-documents repeated document "${document.id}" across pages; refusing an ambiguous result.`,
+        );
+      }
+      documentIds.add(document.id);
+      documents.push(document);
+    }
+
+    const expectedNextOffset = offset + page.documents.length;
+    if (!pagination.hasMore) {
+      if (
+        pagination.nextOffset !== null ||
+        expectedNextOffset !== expectedTotal ||
+        documents.length !== expectedTotal
+      ) {
+        throw new Error(
+          "list-documents claimed exhaustion before every declared document was returned.",
+        );
+      }
+      return documents;
+    }
+    if (
+      pagination.nextOffset !== expectedNextOffset ||
+      pagination.nextOffset <= offset
+    ) {
+      throw new Error(
+        "list-documents returned a non-advancing continuation; refusing a clipped result.",
+      );
+    }
+    offset = pagination.nextOffset;
+  }
+}
+
 export function documentPropertiesQueryKey(
   documentId: string,
   databaseId: string,
@@ -317,11 +387,19 @@ export function seedDatabaseItemDocumentCaches(
 }
 
 export function useDocuments() {
-  return useActionQuery<Document[]>("list-documents", undefined, {
-    select: (data: any) => {
-      const docs = data?.documents ?? data;
-      return Array.isArray(docs) ? docs : [];
-    },
+  return useQuery({
+    queryKey: LIST_DOCUMENTS_QUERY_KEY,
+    queryFn: async ({ signal }) => ({
+      documents: await fetchCompleteDocumentList((offset, limit) =>
+        callAction<DocumentListResponse>(
+          "list-documents",
+          { offset, limit },
+          { method: "GET", signal },
+        ),
+      ),
+    }),
+    select: (data) => data.documents,
+    retry: false,
   });
 }
 

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

@@ -128,6 +128,16 @@ export interface DocumentMoveRequest {
 
 export interface DocumentListResponse {
   documents: Document[];
+  pagination: DocumentDiscoveryPagination;
+}
+
+export interface DocumentDiscoveryPagination {
+  offset: number;
+  limit: number;
+  totalItems: number;
+  returnedItems: number;
+  hasMore: boolean;
+  nextOffset: number | null;
 }
 
 export interface DocumentTreeNode extends Document {

package/corpus/templates/design/.agents/skills/frontend-design/SKILL.md

@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.

package/corpus/templates/dispatch/.agents/skills/frontend-design/SKILL.md

@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.

package/corpus/templates/factory/.agents/skills/frontend-design/SKILL.md

@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.

package/corpus/templates/forms/.agents/skills/frontend-design/SKILL.md

@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.

package/corpus/templates/macros/.agents/skills/frontend-design/SKILL.md

@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.

package/corpus/templates/mail/.agents/skills/frontend-design/SKILL.md

@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.

package/corpus/templates/plan/.agents/skills/frontend-design/SKILL.md

@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.

package/corpus/templates/slides/.agents/skills/frontend-design/SKILL.md

@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.

package/corpus/templates/slides/.agents/skills/slide-editing/SKILL.md

@@ -72,10 +72,17 @@ To edit a slide's content:
 3. **Modify the content** HTML string for the intended slide. Preserve an
    approved native template or component when it already fits; generate
    net-new structure only when the relevant corpus is empty.
-4. **Update the slide** with the `update-slide` action using `deckId`,
-   `slideId`, and `fullContent`. Do not write deck rows directly or add raw
-   full-deck writes for normal slide edits; use `patch-deck` for browser/editor
-   changes.
+4. **Update the slide** with `update-slide` using `deckId`, `slideId`, and
+   ordered `edits`. For code-style work, first read with `get-deck` using the
+   target `slideId`, `compact=false`, and `format=true`, then send the returned
+   `contentHash` as `baseContentHash`. Use exact replace, insert before/after,
+   replace between markers, or regex replace. Set `expectedMatches` whenever a
+   marker could be ambiguous. All edits are applied in memory under the deck
+   lock; if one required edit fails, nothing is written. Set `format=true` on
+   `update-slide` to persist readable Prettier line breaks. Use `fullContent`
+   only for an intentional full rewrite - do not regenerate a slide to make a
+   small change. Do not write deck rows directly or add raw full-deck writes;
+   use `patch-deck` for browser/editor changes.
 5. For browser/editor code, enqueue granular deck operations through
    `patch-deck` / `DeckContext.tsx` instead of replacing the whole deck JSON.
 
@@ -83,6 +90,18 @@ To edit a slide's content:
    preserve quote, speaker, date, metric, and uncertainty status. Existing HTML
    or visual similarity is not proof of source fidelity.
 
+## Click-to-reveal animations
+
+Animations are metadata over the final slide HTML, not alternate slide markup.
+Read the full target slide, keep its existing visual structure, and patch the
+complete ordered `animations` list with `elementPath` values from that exact
+HTML. Elements omitted from the list remain visible immediately, so labels and
+headings need no duplicate markup. Do not add hidden duplicates, layout
+spacers, absolute-positioned copies, transforms, or placeholder content to
+simulate reveals. When content and reveals change together, send both fields in
+one `patch-deck` operation. To remove reveals, send `animations: []` with the
+existing content and verify the persisted slide afterward.
+
 If retrieval produces a new immutable context pack, keep its `contextPackId`
 and reuse labels with the deck provenance. Existing slide HTML is not proof of
 which source version influenced it.

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

@@ -4,7 +4,9 @@ import { getRequestUserEmail } from "@agent-native/core/server/request-context";
 import { resolveAccess } from "@agent-native/core/sharing";
 import { z } from "zod";
 
+import { formatSlideHtml } from "../server/lib/slide-content-patch.js";
 import { summarizeSlideAnimationTargets } from "../server/lib/validate-slide-animations.js";
+import { hashSlideContent } from "../shared/slide-fit.js";
 import "../server/db/index.js"; // ensure registerShareableResource runs
 
 function stripHtml(html: string): string {
@@ -76,6 +78,12 @@ export default defineAction({
       .describe(
         "Set to 'true' for compact slide summaries, or 'false' for full slide HTML. In-app agent calls without slideId default to compact output.",
       ),
+    format: z
+      .enum(["true", "false"])
+      .optional()
+      .describe(
+        "Set to 'true' to return full slide HTML formatted with Prettier for code-style patches. The contentHash still identifies the persisted source.",
+      ),
   }),
   http: { method: "GET" },
   mcpApp: {
@@ -169,6 +177,22 @@ export default defineAction({
     const deckMetadata = { ...data };
     delete deckMetadata.slides;
 
+    const formatHtml = args.format === "true";
+    const fullSlides = await Promise.all(
+      slideEntries.map(async ({ slide: s, index: i }) => ({
+        ...s,
+        slideNumber: i + 1,
+        zeroBasedIndex: i,
+        id: s.id,
+        layout: s.layout ?? null,
+        content: formatHtml
+          ? await formatSlideHtml(String(s.content ?? ""))
+          : s.content,
+        contentHash: hashSlideContent(String(s.content ?? "")),
+        notes: s.notes ?? null,
+      })),
+    );
+
     return {
       ...deckMetadata,
       id: row.id,
@@ -184,15 +208,7 @@ export default defineAction({
       updatedAt: row.updatedAt,
       deepLink: deckDeepLink(row.id),
       ...(selectedSlide ? { selectedSlideId: selectedSlide.id } : {}),
-      slides: slideEntries.map(({ slide: s, index: i }) => ({
-        ...s,
-        slideNumber: i + 1,
-        zeroBasedIndex: i,
-        id: s.id,
-        layout: s.layout ?? null,
-        content: s.content,
-        notes: s.notes ?? null,
-      })),
+      slides: fullSlides,
     };
   },
   link: ({ result, args }) => {

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

@@ -434,6 +434,52 @@ export function applyOperation(deck: any, op: Operation): void {
   }
 }
 
+/**
+ * Agent content rewrites must not inherit click-reveal paths implicitly. A
+ * caller that wants to revise both HTML and reveals sends `animations` in the
+ * same patch, including the complete ordered list. Source-preserving edits are
+ * the exception: they retain imported reveal metadata unless the caller opts
+ * into an explicit source rewrite.
+ */
+export function clearOmittedAnimationsForAgentContentPatches(
+  deck: any,
+  operations: readonly Operation[],
+  options?: { sourceImport?: SourceImportMetadata | null },
+): void {
+  const explicitAnimationSlideIds = new Set(
+    operations.flatMap((operation) =>
+      operation.op === "patch-slide" &&
+      operation.fields.animations !== undefined
+        ? [operation.slideId]
+        : [],
+    ),
+  );
+  const sourceSlideIds = new Set(
+    options?.sourceImport?.slideIds ??
+      options?.sourceImport?.slides.map((slide) => slide.id) ??
+      [],
+  );
+  const slideIds = new Set(
+    operations.flatMap((operation) =>
+      operation.op === "patch-slide" &&
+      operation.fields.content !== undefined &&
+      operation.fields.animations === undefined &&
+      !explicitAnimationSlideIds.has(operation.slideId) &&
+      (operation.preserveSource === false ||
+        !sourceSlideIds.has(operation.slideId))
+        ? [operation.slideId]
+        : [],
+    ),
+  );
+  if (!slideIds.size) return;
+
+  for (const slide of Array.isArray(deck.slides) ? deck.slides : []) {
+    if (slideIds.has(slide?.id) && Array.isArray(slide.animations)) {
+      delete slide.animations;
+    }
+  }
+}
+
 /**
  * Content and animation metadata are one contract. Validate only slides whose
  * content or animation list changed so unrelated note/title writes do not
@@ -620,6 +666,11 @@ export default defineAction({
       for (const op of operations) {
         applyOperation(deck, op);
       }
+      if (isAgentCaller) {
+        clearOmittedAnimationsForAgentContentPatches(deck, operations, {
+          sourceImport,
+        });
+      }
       assertPatchedSlideAnimationsResolve(deck, operations, {
         requireElementPaths: isAgentCaller,
       });