@agent-native/core 0.122.4 → 0.123.0

package/corpus/templates/slides/actions/_deck-write.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared helpers for the editor-owned deck write actions (`add-deck`,
+ * `save-deck`, `delete-deck`). Underscore-prefixed so action discovery skips
+ * it — this module is not itself an action.
+ */
+import { assertAccess, ForbiddenError } from "@agent-native/core/sharing";
+
+import { ASPECT_RATIO_VALUES } from "../shared/aspect-ratios.js";
+
+/** A deck is stored as one opaque JSON blob in `decks.data`. */
+export type DeckPayload = Record<string, unknown>;
+
+/**
+ * Actions surface HTTP status through `statusCode`; the action route echoes the
+ * message verbatim for client errors and swallows it for anything >= 500.
+ */
+export function deckHttpError(statusCode: number, message: string): Error {
+  return Object.assign(new Error(message), { statusCode });
+}
+
+export function deckTitle(deck: DeckPayload): string {
+  return typeof deck.title === "string" && deck.title ? deck.title : "Untitled";
+}
+
+export function deckDesignSystemId(deck: DeckPayload): string | null {
+  return typeof deck.designSystemId === "string" && deck.designSystemId
+    ? deck.designSystemId
+    : null;
+}
+
+export function assertValidAspectRatio(deck: DeckPayload): void {
+  if (
+    "aspectRatio" in deck &&
+    !ASPECT_RATIO_VALUES.includes(deck.aspectRatio as never)
+  ) {
+    throw deckHttpError(400, "Invalid aspect ratio");
+  }
+}
+
+export async function assertDesignSystemReadable(
+  designSystemId: string | null,
+): Promise<void> {
+  if (!designSystemId) return;
+  try {
+    await assertAccess("design-system", designSystemId, "viewer");
+  } catch (err) {
+    if (err instanceof ForbiddenError) {
+      throw deckHttpError(400, "Design system not accessible");
+    }
+    throw err;
+  }
+}

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

@@ -0,0 +1,73 @@
+/**
+ * add-deck — insert a deck the browser editor has already created optimistically.
+ *
+ * The editor mints the deck id client-side (so the optimistic row and its URL
+ * are stable before the round trip), which is why this is separate from
+ * `create-deck`: that action generates its own id and owns the agent's
+ * generation flow. Hidden from the agent — deck creation for the model goes
+ * through `create-deck`.
+ */
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { notifyClients } from "../server/handlers/decks.js";
+import {
+  assertDesignSystemReadable,
+  assertValidAspectRatio,
+  deckDesignSystemId,
+  deckHttpError,
+  deckTitle,
+  type DeckPayload,
+} from "./_deck-write.js";
+
+export default defineAction({
+  description:
+    "Insert a new deck owned by the caller from a client-generated deck payload.",
+  schema: z.object({
+    deck: z
+      .record(z.string(), z.unknown())
+      .describe("Full deck JSON payload, including its client-generated id"),
+  }),
+  agentTool: false,
+  run: async (args) => {
+    const deck = args.deck as DeckPayload;
+    const id = deck.id;
+    if (typeof id !== "string" || !id) {
+      throw deckHttpError(400, "Deck must have an id");
+    }
+    assertValidAspectRatio(deck);
+
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) {
+      throw deckHttpError(403, "Sign in to create a deck");
+    }
+
+    const now = new Date().toISOString();
+    deck.createdAt = deck.createdAt || now;
+    deck.updatedAt = now;
+
+    const designSystemId = deckDesignSystemId(deck);
+    await assertDesignSystemReadable(designSystemId);
+
+    await getDb()
+      .insert(schema.decks)
+      .values({
+        id,
+        title: deckTitle(deck),
+        data: JSON.stringify(deck),
+        designSystemId,
+        ownerEmail,
+        orgId: getRequestOrgId() ?? null,
+        createdAt: now,
+        updatedAt: now,
+      });
+
+    notifyClients(id);
+    return deck;
+  },
+});

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

@@ -0,0 +1,60 @@
+/**
+ * delete-deck — remove a deck and its version history.
+ *
+ * Hidden from the agent: deck deletion has always been a UI-only operation and
+ * this action exists to give the editor the same permission rule it had on the
+ * route it replaced.
+ */
+import { defineAction } from "@agent-native/core";
+import { assertAccess, ForbiddenError } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { notifyClients } from "../server/handlers/decks.js";
+import { deckHttpError } from "./_deck-write.js";
+
+export default defineAction({
+  description: "Delete a deck and its saved versions.",
+  schema: z.object({
+    id: z.string().min(1).describe("Deck ID"),
+  }),
+  http: { method: "DELETE" },
+  agentTool: false,
+  run: async ({ id }) => {
+    try {
+      // assertAccess loads the row and verifies the caller has admin role on
+      // this resource — it must run BEFORE the delete so we don't leak
+      // existence to callers who lack access.
+      const access = await assertAccess("deck", id, "admin");
+      const db = getDb();
+      await db
+        .delete(schema.deckVersions)
+        .where(
+          and(
+            eq(schema.deckVersions.deckId, id),
+            eq(
+              schema.deckVersions.ownerEmail,
+              access.resource.ownerEmail as string,
+            ),
+          ),
+        );
+      const result = await db
+        .delete(schema.decks)
+        .where(eq(schema.decks.id, id))
+        .returning();
+
+      if (result.length === 0) {
+        throw deckHttpError(404, "Deck not found");
+      }
+      notifyClients(id, "deck-deleted");
+      return { success: true };
+    } catch (err) {
+      // 404 rather than 403 so callers can't probe for decks they can't see.
+      if (err instanceof ForbiddenError) {
+        throw deckHttpError(404, "Deck not found");
+      }
+      throw err;
+    }
+  },
+});

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

@@ -52,7 +52,9 @@ export default defineAction({
 
     const access = await resolveAccess("deck", args.id);
     if (!access) {
-      throw new Error("Deck not found");
+      // 404 rather than 403/500 so HTTP callers can't probe for decks they
+      // can't see, and so the slide preview can tell "missing" from "broken".
+      throw Object.assign(new Error("Deck not found"), { statusCode: 404 });
     }
 
     const row = access.resource;

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

@@ -0,0 +1,144 @@
+/**
+ * save-deck — create-or-replace a deck's whole JSON payload.
+ *
+ * The browser editor saves through `patch-deck`; this full-payload write is
+ * reserved for the paths that already hold an authoritative snapshot (undo/redo
+ * and bulk slide replacement). Hidden from the agent, which edits through
+ * `patch-deck`, `update-slide`, and `add-slide` so concurrent writers on
+ * different slides don't clobber each other.
+ */
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { resolveAccess } from "@agent-native/core/sharing";
+import { eq } from "drizzle-orm";
+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 {
+  assertDesignSystemReadable,
+  assertValidAspectRatio,
+  deckDesignSystemId,
+  deckHttpError,
+  deckTitle,
+  type DeckPayload,
+} from "./_deck-write.js";
+import { withDeckLock } from "./patch-deck.js";
+
+function comparableDeckData(raw: unknown): string {
+  try {
+    const data = typeof raw === "string" ? JSON.parse(raw) : raw;
+    const clone = JSON.parse(JSON.stringify(data ?? {}));
+    delete clone.updatedAt;
+    return JSON.stringify(clone);
+  } catch {
+    return String(raw ?? "");
+  }
+}
+
+function shouldSnapshotDeckWrite(
+  current: { title?: string | null; data?: string | null },
+  nextTitle: string,
+  nextDeck: DeckPayload,
+): boolean {
+  return (
+    (current.title ?? "Untitled") !== nextTitle ||
+    comparableDeckData(current.data ?? "") !== comparableDeckData(nextDeck)
+  );
+}
+
+export default defineAction({
+  description:
+    "Create or replace a deck's full JSON payload (title, slides, deck-level fields).",
+  schema: z.object({
+    deckId: z.string().min(1).describe("Deck ID"),
+    deck: z.record(z.string(), z.unknown()).describe("Full deck JSON payload"),
+  }),
+  http: { method: "PUT" },
+  agentTool: false,
+  run: async (args) =>
+    withDeckLock(args.deckId, async () => {
+      const deckId = args.deckId;
+      const deck = args.deck as DeckPayload;
+      assertValidAspectRatio(deck);
+
+      const db = getDb();
+      const now = new Date().toISOString();
+
+      deck.id = deckId;
+      deck.updatedAt = now;
+      const title = deckTitle(deck);
+      const nextDesignSystemId = deckDesignSystemId(deck);
+
+      // Resolve access first — this loads the row AND tells us the caller's
+      // effective role in one pass, so we never run an unscoped existence
+      // SELECT that would leak "this id exists" to non-owners.
+      const access = await resolveAccess("deck", deckId);
+
+      if (!access) {
+        // Either the deck does not exist OR the caller cannot see it. In both
+        // cases we treat this as a create for the caller. If the row actually
+        // exists but is owned by someone else, the INSERT below fails on the
+        // primary key — mapped to a 404 so we never reveal that the id is taken.
+        const ownerEmail = getRequestUserEmail();
+        if (!ownerEmail) {
+          throw deckHttpError(403, "Sign in to create a deck");
+        }
+        await assertDesignSystemReadable(nextDesignSystemId);
+        try {
+          await db.insert(schema.decks).values({
+            id: deckId,
+            title,
+            data: JSON.stringify(deck),
+            designSystemId: nextDesignSystemId,
+            ownerEmail,
+            orgId: getRequestOrgId() ?? null,
+            createdAt: now,
+            updatedAt: now,
+          });
+        } catch {
+          // Some adapters wrap duplicate-key failures in a generic query error
+          // that includes bound params, so never surface the raw error here.
+          throw deckHttpError(404, "Deck not found");
+        }
+      } else if (
+        access.role === "owner" ||
+        access.role === "admin" ||
+        access.role === "editor"
+      ) {
+        await assertDesignSystemReadable(nextDesignSystemId);
+        if (shouldSnapshotDeckWrite(access.resource, title, deck)) {
+          await createDeckVersionSnapshot(
+            {
+              id: access.resource.id,
+              title: access.resource.title,
+              data: access.resource.data,
+              ownerEmail: access.resource.ownerEmail as string,
+            },
+            { label: "Before editor save" },
+          );
+        }
+        await db
+          .update(schema.decks)
+          .set({
+            title,
+            data: JSON.stringify(deck),
+            designSystemId:
+              nextDesignSystemId ?? access.resource.designSystemId,
+            updatedAt: now,
+          })
+          .where(eq(schema.decks.id, deckId));
+      } else {
+        // Viewer-only access — same 404 as no-access so we don't leak that the
+        // deck exists with restricted permissions.
+        throw deckHttpError(404, "Deck not found");
+      }
+
+      notifyClients(deckId);
+      return deck;
+    }),
+});

package/corpus/templates/slides/app/components/editor/SlideEditor.tsx

@@ -1101,6 +1101,12 @@ export default function SlideEditor({
   const marqueePrevSelectionRef = useRef<Set<string>>(new Set());
   /** Currently-edited smart block (leaf or group). State, not ref, so menu re-renders. */
   const [editingEl, setEditingEl] = useState<HTMLElement | null>(null);
+  /**
+   * Mirror of `editingEl` readable outside render. Exit paths must not read it
+   * through a `setEditingEl` updater: updaters run during the render phase, so
+   * the parent's `onUpdateSlide` would update DeckProvider mid-render.
+   */
+  const editingElRef = useRef<HTMLElement | null>(null);
   /** Latest onUpdateSlide in a ref so blur handlers always see the current version */
   const onUpdateSlideRef = useRef(onUpdateSlide);
   useEffect(() => {
@@ -1203,19 +1209,19 @@ export default function SlideEditor({
 
   /** Exit edit mode, saving changes to slide.content */
   const exitInlineEdit = useCallback(() => {
-    setEditingEl((el) => {
-      if (!el) return null;
-      el.contentEditable = "false";
-      el.removeAttribute("data-editing-block");
-
-      const html = readCurrentSlideContentHtml();
-      if (html !== null) {
-        onUpdateSlideRef.current({ content: html });
-      }
-      inlineEditDraftRef.current = null;
-      syncSelectionToAppState(null);
-      return null;
-    });
+    const el = editingElRef.current;
+    if (!el) return;
+    editingElRef.current = null;
+    el.contentEditable = "false";
+    el.removeAttribute("data-editing-block");
+
+    const html = readCurrentSlideContentHtml();
+    if (html !== null) {
+      onUpdateSlideRef.current({ content: html });
+    }
+    inlineEditDraftRef.current = null;
+    syncSelectionToAppState(null);
+    setEditingEl(null);
   }, [readCurrentSlideContentHtml]);
 
   /** Enter edit mode on a smart block (text leaf or smart group) */
@@ -1239,6 +1245,7 @@ export default function SlideEditor({
       // element that already contains the selection preserves it in modern
       // browsers, so it's safe to keep for keyboard delivery.
       el.focus({ preventScroll: true });
+      editingElRef.current = el;
       setEditingEl(el);
       if (selector) {
         syncSelectionToAppState(
@@ -1263,13 +1270,13 @@ export default function SlideEditor({
     if (previousSlideId === slide.id) return;
 
     const draft = inlineEditDraftRef.current;
-    setEditingEl((el) => {
-      if (el) {
-        el.contentEditable = "false";
-        el.removeAttribute("data-editing-block");
-      }
-      return null;
-    });
+    const editing = editingElRef.current;
+    if (editing) {
+      editing.contentEditable = "false";
+      editing.removeAttribute("data-editing-block");
+    }
+    editingElRef.current = null;
+    setEditingEl(null);
 
     if (draft?.slideId === previousSlideId) {
       onUpdateSlideRef.current({ content: draft.content }, previousSlideId);