@agent-native/core 0.149.1 → 0.149.3

package/corpus/templates/slides/app/root.tsx

@@ -33,6 +33,10 @@ import {
 } from "react-router";
 import type { LinksFunction } from "react-router";
 
+import {
+  getEditorCommands,
+  type EditorCommandGroup,
+} from "@/components/editor/editor-command-model";
 import { Layout as AppLayout } from "@/components/layout/Layout";
 import { FirstDeckOnboardingFlow } from "@/components/onboarding/FirstDeckOnboardingFlow";
 import { AppToolkitProvider } from "@/components/ui/toolkit-provider";
@@ -202,6 +206,17 @@ function AppContent() {
   const navigate = useNavigate();
   useCommandMenuShortcut(useCallback(() => setCmdkOpen(true), []));
   const location = useLocation();
+  const editorCommands = getEditorCommands();
+  const editorCommandGroups: Array<{
+    id: EditorCommandGroup;
+    heading: string;
+  }> = [
+    { id: "media", heading: t("editorToolbar.media") },
+    { id: "slideTools", heading: t("editorToolbar.slideTools") },
+    { id: "comments", heading: t("editorToolbar.comments") },
+    { id: "deck", heading: t("editorExport.exportAndDuplicate") },
+    { id: "other", heading: t("editorToolbar.more") },
+  ];
 
   const isBare =
     BARE_ROUTES.has(location.pathname) ||
@@ -236,6 +251,34 @@ function AppContent() {
             {t("settings.openAgentSettings")}
           </CommandMenu.Item>
         </CommandMenu.Group>
+        {editorCommandGroups.map((group) => {
+          const commands = editorCommands.filter(
+            (command) => command.group === group.id,
+          );
+          if (commands.length === 0) return null;
+          return (
+            <CommandMenu.Group key={group.id} heading={group.heading}>
+              {commands.map((command) => {
+                const Icon = command.icon;
+                return (
+                  <CommandMenu.Item
+                    key={command.id}
+                    onSelect={command.run}
+                    keywords={command.keywords}
+                    className={
+                      command.active
+                        ? "bg-accent text-accent-foreground"
+                        : undefined
+                    }
+                  >
+                    {Icon ? <Icon size={16} /> : null}
+                    {command.label}
+                  </CommandMenu.Item>
+                );
+              })}
+            </CommandMenu.Group>
+          );
+        })}
         <CommandMenu.Group heading={t("root.commandAppearance")}>
           <CommandMenu.Item
             onSelect={() => setTheme(isDark ? "light" : "dark")}

package/corpus/templates/slides/changelog/2026-08-10-ai-editing-avatar-badge.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-10
+---
+
+AI editing status now uses a cleaner combined avatar badge.

package/corpus/templates/slides/changelog/2026-08-10-generated-decks-keep-a-clear-human-readable-title.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-10
+---
+
+Generated decks keep a clear, human-readable title

package/corpus/templates/slides/changelog/2026-08-10-new-deck-creation-now-shows-progress-opens-the-editor-direct.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-10
+---
+
+New deck creation now shows progress, opens the editor directly, and remembers your reference choices

package/corpus/templates/slides/changelog/2026-08-10-presentation-reveals-now-follow-valid-targets.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-10
+---
+
+Presentation reveals now follow validated ordered targets, queue rapid navigation, and settle cleanly after transitions.

package/corpus/templates/slides/changelog/2026-08-10-slides-editing-controls-are-consolidated-into-one-focused-me.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-10
+---
+
+Slides editing controls are consolidated into one focused menu

package/corpus/templates/slides/changelog/2026-08-10-slides-now-verify-and-restyle-every-imported-slide-in-one-pa.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-10
+---
+
+Slides now verify and restyle every imported slide in one pass

package/corpus/templates/slides/changelog/2026-08-10-slides-only-suggests-a-google-connection-for-relevant-reques.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-10
+---
+
+Slides only suggests a Google connection for relevant requests, and the suggestion can be dismissed.

package/corpus/templates/slides/changelog/2026-08-10-the-google-slides-import-option-is-now-labeled-slides.md

@@ -0,0 +1,6 @@
+---
+type: changed
+date: 2026-08-10
+---
+
+The Google Slides import option is now labeled Slides.

package/corpus/templates/slides/changelog/2026-08-11-faster-slides-chat-deck-reads.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-11
+---
+
+Faster Slides chat deck reads

package/corpus/templates/slides/changelog/2026-08-11-slides-chat-can-read-one-slide-without-loading-the-full-deck.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-11
+---
+
+Slides chat can read one slide without loading the full deck

package/corpus/templates/slides/changelog/2026-08-11-slides-clearly-indicate-when-an-ai-agent-is-editing-alongsid.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-11
+---
+
+Slides clearly indicate when an AI agent is editing alongside you.

package/corpus/templates/slides/package.json

@@ -48,6 +48,7 @@
     "isbot": "^5",
     "jspdf": "4.2.1",
     "jszip": "3.10.1",
+    "linkedom": "0.18.13",
     "mammoth": "1.12.0",
     "mermaid": "^11.14.0",
     "modern-screenshot": "^4.7.0",

package/corpus/templates/slides/server/lib/chat-attachments.ts

@@ -119,7 +119,7 @@ export async function prepareSlidesChatAttachments(args: {
           "",
           "File handling rules:",
           "- If the request refers to the current or visible deck, call `view-screen` first to confirm the active deckId, then pass that deckId to import or slide-edit actions.",
-          '- PPTX files: when the user wants the visible deck improved, call `import-pptx --filePath "<path>" --deckId <deckId>` first, then edit those imported slide IDs in place with update-slide. Do not rebuild the source deck with add-slide.',
+          '- PPTX files: when the user wants the visible deck improved, call `import-pptx --filePath "<path>" --deckId <deckId>` first, then use one patch-deck call with requireAllSourceSlides=true and one content patch per imported slide for a deck-wide restyle. Use update-slide only for a targeted one-slide edit. Do not rebuild the source deck with add-slide.',
           '- PDF and DOCX files: call `import-file --filePath "<path>" --format auto --deckId <deckId>` and use the returned extracted text as source material before creating editable slides. For a visual PDF that the user wants preserved, beautified, or restyled from its original layout, pass `--importIntoDeck true` so each page is imported source-faithfully first; keep the full-page image and style around it, with source text persisted in slide notes for inspection.',
           '- Figma `.fig` files: call `import-file --filePath "<path>" --format fig` to start Builder design-system indexing. Do not create a local design system directly from the upload.',
           "- For deck-generation requests, start mutating promptly: create or update the first slide as soon as source material is extracted, then continue slide-by-slide with add-slide/update-slide.",

package/corpus/templates/slides/server/lib/validate-slide-animations.ts

@@ -0,0 +1,163 @@
+import { parseHTML } from "linkedom/worker";
+
+import {
+  animationElementKey,
+  getElementPath,
+  getElementPreview,
+  resolveSlideAnimationElement,
+  resolveSlideAnimationTargetsWithDiagnostics,
+  type AnimationTarget,
+} from "../../app/lib/slide-animation-elements.js";
+
+interface SlideAnimation extends AnimationTarget {
+  id?: string;
+}
+
+export interface SlideAnimationTargetSummary {
+  targetPreview: string | null;
+  resolvedPath: string | null;
+  targetValid: boolean;
+  targetIssue:
+    | "missing-slide-root"
+    | "target-not-found"
+    | "duplicate-target"
+    | null;
+}
+
+function formatTarget(target: SlideAnimation): string {
+  const id = target.id ? ` (${target.id})` : "";
+  const path = Array.isArray(target.elementPath)
+    ? ` path [${target.elementPath.join(", ")}]`
+    : "";
+  return `step ${target.elementIndex + 1}${id}${path}`;
+}
+
+export function summarizeSlideAnimationTargets(
+  content: string,
+  animations: readonly SlideAnimation[],
+): SlideAnimationTargetSummary[] {
+  if (animations.length === 0) return [];
+
+  const { document } = parseHTML(
+    `<!doctype html><html><head></head><body>${content}</body></html>`,
+  );
+  const root = document.querySelector(".fmd-slide");
+  if (!root) {
+    return animations.map(() => ({
+      targetPreview: null,
+      resolvedPath: null,
+      targetValid: false,
+      targetIssue: "missing-slide-root",
+    }));
+  }
+
+  const seen = new Set<string>();
+  return animations.map((target) => {
+    const element = resolveSlideAnimationElement(root, target);
+    if (!element) {
+      return {
+        targetPreview: null,
+        resolvedPath: null,
+        targetValid: false,
+        targetIssue: "target-not-found",
+      };
+    }
+
+    const path = getElementPath(root, element);
+    if (!path) {
+      return {
+        targetPreview: getElementPreview(
+          element,
+          `Element ${target.elementIndex + 1}`,
+        ),
+        resolvedPath: null,
+        targetValid: false,
+        targetIssue: "target-not-found",
+      };
+    }
+
+    const key = animationElementKey(path);
+    if (seen.has(key)) {
+      return {
+        targetPreview: getElementPreview(
+          element,
+          `Element ${target.elementIndex + 1}`,
+        ),
+        resolvedPath: key,
+        targetValid: false,
+        targetIssue: "duplicate-target",
+      };
+    }
+
+    seen.add(key);
+    return {
+      targetPreview: getElementPreview(
+        element,
+        `Element ${target.elementIndex + 1}`,
+      ),
+      resolvedPath: key,
+      targetValid: true,
+      targetIssue: null,
+    };
+  });
+}
+
+/**
+ * Validate animation identity against the exact HTML that is about to be
+ * persisted. Playback cannot repair a stale path without risking a different
+ * element being revealed, so reject the mutation before the deck is written.
+ */
+export function assertSlideAnimationsResolve({
+  slideId,
+  content,
+  animations,
+  requireElementPaths = false,
+}: {
+  slideId: string;
+  content: string;
+  animations: readonly SlideAnimation[];
+  requireElementPaths?: boolean;
+}): void {
+  if (animations.length === 0) return;
+
+  if (requireElementPaths) {
+    const legacyIndex = animations.findIndex(
+      (animation) => !Array.isArray(animation.elementPath),
+    );
+    if (legacyIndex !== -1) {
+      const target = animations[legacyIndex];
+      throw new Error(
+        `Cannot save animations for slide ${slideId}: ${target ? formatTarget(target) : `step ${legacyIndex + 1}`} is missing elementPath. Agent-created or content-revised animations must use a path from the final HTML; elementIndex-only targets are legacy-only.`,
+      );
+    }
+  }
+
+  const { document } = parseHTML(
+    `<!doctype html><html><head></head><body>${content}</body></html>`,
+  );
+  const root = document.querySelector(".fmd-slide");
+  if (!root) {
+    throw new Error(
+      `Cannot save animations for slide ${slideId}: the final HTML has no .fmd-slide wrapper. Re-read the slide content, then send the content and complete animation list together.`,
+    );
+  }
+
+  const resolution = resolveSlideAnimationTargetsWithDiagnostics(
+    root,
+    animations,
+  );
+  const issue = resolution.issue;
+  if (!issue) return;
+
+  const target = animations[issue.animationIndex];
+  const targetDescription = target ? formatTarget(target) : "unknown step";
+  if (issue.code === "duplicate-target") {
+    throw new Error(
+      `Cannot save animations for slide ${slideId}: ${targetDescription} duplicates target path ${issue.key ?? "unknown"}${issue.preview ? ` (${issue.preview})` : ""}. Each reveal step must target a different element; re-read the final HTML and send the complete ordered list.`,
+    );
+  }
+
+  throw new Error(
+    `Cannot save animations for slide ${slideId}: ${targetDescription} does not resolve in the final HTML. Do not fall back to elementIndex; re-read the final HTML and send the content and complete ordered animation list together.`,
+  );
+}

package/corpus/templates/slides/server/plugins/agent-chat.ts

@@ -52,23 +52,26 @@ export default createAgentChatPlugin({
   prepareRequest: prepareSlidesChatAttachments,
   systemPrompt: `You are an AI deck assistant. You create, edit, import, export, style, share, and navigate decks through actions and shared application state. For a newly created presentation, use create-deck with slides: [] only when you are creating the deck yourself, then add-slide sequentially with full rendered HTML. The legacy generate-slides-ai action returns Markdown drafts and is not part of the persisted presentation workflow.
 
-When the user asks to improve, beautify, restyle, or make an uploaded/existing deck on-brand, treat it as an in-place source-preserving edit unless the user explicitly asks to rewrite the story or change slide count. First call view-screen when the active deck is unclear, then get-deck. If get-deck.sourceImport exists, preserve its slide count, order, IDs, factual copy, notes, images, charts, tables, diagrams, freeform objects, and source aspect ratio. Use update-slide on existing slide IDs. Do not use add-slide, delete, reorder, or replace source imagery with generic cards for this workflow. Verify the same slide IDs and count with get-deck after editing. If sourceImport.fidelity is partial or imagesSkipped is nonzero, stop and report the exact fidelity warning instead of claiming a reliable improvement.
+When the user asks to improve, beautify, restyle, or make an uploaded/existing deck on-brand, treat it as an in-place source-preserving edit unless the user explicitly asks to rewrite the story or change slide count. First call view-screen when the active deck is unclear, then get-deck with compact=true for deck orientation. If you need slide markup, call get-deck with compact=false explicitly and only when the edit requires the full HTML. If get-deck.sourceImport exists, preserve its slide count, order, IDs, factual copy, notes, images, charts, tables, diagrams, freeform objects, and source aspect ratio. For a deck-wide restyle, use one patch-deck call with requireAllSourceSlides=true and one patch-slide operation with fields.content for every source slide ID; the action rejects partial coverage. Do not split a full-deck restyle into arbitrary batches or use one-by-one update-slide calls - reserve update-slide for targeted one-slide edits. After the patch succeeds, verify with get-deck using compact=true so the verification does not retransmit every slide's HTML. Do not claim a partial or initial pass. Do not use add-slide, delete, reorder, or replace source imagery with generic cards for this workflow. If sourceImport.fidelity is partial or imagesSkipped is nonzero, stop and report the exact fidelity warning instead of claiming a reliable improvement.
+For a targeted one-slide edit, prefer get-deck with the stable slideId from view-screen or compact get-deck. It returns only that slide's full HTML by default, so do not load the full deck when one slide is enough. Pass compact=true when you only need a lightweight check of that slide.
 
-For source-faithful PDF slides, keep the original full-page image and style around it with restrained design-system chrome such as a frame, edge treatment, caption, or safe overlay that does not obscure source content; never OCR-reconstruct the page from extracted text. For PPTX slides, preserve the imported positioned HTML and every uploaded source image. The update-slide action enforces these preservation rules by default; pass preserveSource=false only when the user explicitly requests a rewrite of that slide.
+When the active Slides editor is already showing the deck you just changed, do not include an "Open the updated deck" or similar link in the final response. The deck is already open and the action updated it in place; say that plainly instead. Only provide an open-deck link when the user is elsewhere, the active deck is different, or the user explicitly asks for a link.
+
+For source-faithful PDF slides, keep the original full-page image and style around it with restrained design-system chrome such as a frame, edge treatment, caption, or safe overlay that does not obscure source content; never OCR-reconstruct the page from extracted text. For PPTX slides, preserve the imported positioned HTML and every uploaded source image. The patch-deck and update-slide actions enforce these preservation rules by default; pass preserveSource=false only when the user explicitly requests a rewrite of that slide.
 
 If the deck has designSystemId, call get-design-system before writing and follow its exact agentContext tokens, assets, and custom instructions. If the user asks for on-brand styling and no design system is linked, call get-workspace-defaults, link its usable design system with patch-deck, then call get-design-system. Do not improvise a generic Builder-like palette when configured Builder.io design-system context is available.
 
-Layout-fit workflow is strict. When the user asks to fix overflow, first call view-screen and inspect the deck-wide layout-fit section. If it says measurements are unknown, do not claim the deck fits. Call get-layout-overflows when you need the structured per-slide results. Read the affected slides with get-deck, then make one bounded structural repair pass with one patch-slide operation per affected slide in a single patch-deck call. Wait for the action result and verify the persisted HTML with get-deck before saying it is fixed. If a fresh measurement still reports overflow, make at most one focused follow-up repair based on that measurement; never loop, repeatedly re-measure, or claim success after a chat response alone.
+Layout-fit workflow is strict. When the user asks to fix overflow, first call view-screen and inspect the deck-wide layout-fit section. If it says measurements are unknown, do not claim the deck fits. Call get-layout-overflows when you need the structured per-slide results. Read each affected slide with get-deck slideId=<id> (full HTML is returned for a targeted read), then make one bounded structural repair pass with one patch-slide operation per affected slide in a single patch-deck call. Wait for the action result and verify the persisted HTML with get-deck slideId=<id> compact=true before saying it is fixed. If a fresh measurement still reports overflow, make at most one focused follow-up repair based on that measurement; never loop, repeatedly re-measure, or claim success after a chat response alone.
 
 Fit means the main content fits the native content area. A small outer-wrapper spill is tolerated by the measurement, but cards, text, columns, and other visible content must fit. Never use zoom, transform: scale(), overflow: hidden/scroll, clipping, or a smaller-than-16px body font to hide overflow. Preserve manually positioned freeform objects and their data-slide-object-id values; repair normal-flow structure, copy, gaps, or slide padding instead. A successful action result must include the affected slide IDs; if it does not, report that no verified write occurred.
 
-Image workflow is strict. For direct insertion, call generate-image-api with insertIntoSlide: true plus deckId and slideId. Claim that an image was added only when that action returns inserted: true; a preview URL or completed generation alone is not a slide edit. For preview-only variations, call generate-image-api without insertIntoSlide, then use update-slide to place the chosen URL and re-read the target with get-deck to confirm its persisted HTML contains that image source before claiming success.
+Image workflow is strict. For direct insertion, call generate-image-api with insertIntoSlide: true plus deckId and slideId. Claim that an image was added only when that action returns inserted: true; a preview URL or completed generation alone is not a slide edit. For preview-only variations, call generate-image-api without insertIntoSlide, then use update-slide to place the chosen URL and re-read the target with get-deck slideId=<id> compact=false to confirm its persisted HTML contains that image source before claiming success.
 
 Provider-specific Slides actions are shortcuts, not limits. If a first-class action cannot express the exact Google Drive endpoint, file metadata field, export format, query, request body, pagination mode, payload shape, or API version needed, call provider-api-catalog and provider-api-docs as needed, then call provider-api-request against the real provider API. Use the raw provider API escape hatch instead of weakening the answer or claiming Slides cannot do something the underlying Google Drive API can do.
 
 Slides' Google Drive provider API uses the user's connected Google Docs OAuth account. Picker imports keep the per-file drive.file path, while pasted Google Slides links use Drive export access and may ask the user to reconnect Google. For large Drive file lists or metadata sweeps, pass stageAs and pagination options to provider-api-request, then use query-staged-dataset to count, filter, group, or project the staged rows.
 
-When a Google Drive or Google Slides request needs authentication, tell the user to use the Connect Google button shown in Slides. Do not expose internal routes, API endpoints, OAuth setup instructions, client IDs, or keys in the response, and do not ask the user to configure an API manually.`,
+When a Google Drive or Google Slides request needs authentication, tell the user to use the Connect Google button in the Google Slides import step. Do not expose internal routes, API endpoints, OAuth setup instructions, client IDs, or keys in the response, and do not ask the user to configure an API manually.`,
   mentionProviders: async () => {
     const { getDb } = await import("../db/index.js");
     const { decks, deckShares } = await import("../db/schema.js");

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

@@ -95,6 +95,18 @@ export type SharedSlideTransition =
 
 export type SharedAnimationType = "appear" | "fade" | "slide-up" | "zoom";
 
+export type SharedAnimationIssueCode =
+  | "invalid-shape"
+  | "invalid-element-path"
+  | "missing-target"
+  | "unsupported-type";
+
+export interface SharedSlideAnimationIssue {
+  index: number;
+  id: string | null;
+  code: SharedAnimationIssueCode;
+}
+
 export interface SharedSlideAnimation {
   id: string;
   elementIndex: number;
@@ -110,6 +122,7 @@ export interface SharedDeckSlide {
   background?: string;
   transition?: SharedSlideTransition;
   animations?: SharedSlideAnimation[];
+  animationIssues?: SharedSlideAnimationIssue[];
   splitByParagraph?: boolean;
 }
 
@@ -137,7 +150,7 @@ function normalizeString(value: unknown, fallback: string): string {
 }
 
 function normalizeElementPath(value: unknown): number[] | undefined {
-  if (!Array.isArray(value)) return undefined;
+  if (!Array.isArray(value) || value.length === 0) return undefined;
   const path = value.filter(
     (part): part is number =>
       typeof part === "number" &&
@@ -151,10 +164,18 @@ function normalizeElementPath(value: unknown): number[] | undefined {
 function normalizeSlideAnimation(
   value: unknown,
   index: number,
-): SharedSlideAnimation | null {
-  if (!isRecord(value)) return null;
+): { animation: SharedSlideAnimation } | { issue: SharedSlideAnimationIssue } {
+  const id = isRecord(value) && typeof value.id === "string" ? value.id : null;
+  const issue = (code: SharedAnimationIssueCode) => ({
+    issue: { index, id, code },
+  });
+
+  if (!isRecord(value)) return issue("invalid-shape");
 
   const elementPath = normalizeElementPath(value.elementPath);
+  if (value.elementPath !== undefined && !elementPath) {
+    return issue("invalid-element-path");
+  }
   const rawElementIndex = value.elementIndex;
   const hasElementIndex =
     typeof rawElementIndex === "number" &&
@@ -162,12 +183,13 @@ function normalizeSlideAnimation(
     Number.isFinite(rawElementIndex) &&
     rawElementIndex >= 0;
 
-  if (!hasElementIndex && !elementPath) return null;
+  if (!hasElementIndex && !elementPath) return issue("missing-target");
 
   const rawType = value.type;
-  const type = SHARED_ANIMATION_TYPES.has(rawType as SharedAnimationType)
-    ? (rawType as SharedAnimationType)
-    : "slide-up";
+  if (!SHARED_ANIMATION_TYPES.has(rawType as SharedAnimationType)) {
+    return issue("unsupported-type");
+  }
+  const type = rawType as SharedAnimationType;
 
   // When an explicit `elementIndex` is present, trust it. Otherwise derive
   // from the last segment of `elementPath` - keeps the index correlated
@@ -182,10 +204,12 @@ function normalizeSlideAnimation(
     : (elementPath![elementPath!.length - 1] ?? 0);
 
   return {
-    id: normalizeString(value.id, `animation-${index + 1}`),
-    elementIndex: resolvedElementIndex,
-    ...(elementPath ? { elementPath } : {}),
-    type,
+    animation: {
+      id: normalizeString(value.id, `animation-${index + 1}`),
+      elementIndex: resolvedElementIndex,
+      ...(elementPath ? { elementPath } : {}),
+      type,
+    },
   };
 }
 
@@ -214,14 +238,22 @@ export function toSharedDeckSlide(
   }
 
   if (Array.isArray(slide.animations)) {
-    const animations = slide.animations
-      .map((animation, animationIndex) =>
+    const normalizedAnimations = slide.animations.map(
+      (animation, animationIndex) =>
         normalizeSlideAnimation(animation, animationIndex),
-      )
-      .filter((animation): animation is SharedSlideAnimation => !!animation);
+    );
+    const animations = normalizedAnimations.flatMap((result) =>
+      "animation" in result ? [result.animation] : [],
+    );
+    const animationIssues = normalizedAnimations.flatMap((result) =>
+      "issue" in result ? [result.issue] : [],
+    );
     if (animations.length > 0) {
       shared.animations = animations;
     }
+    if (animationIssues.length > 0) {
+      shared.animationIssues = animationIssues;
+    }
   }
 
   return shared;

package/corpus/templates/slides/shared/deck-title.ts

@@ -0,0 +1,135 @@
+const GENERATED_TITLE_PLACEHOLDERS = new Set([
+  "deck",
+  "date",
+  "image slide title",
+  "presentation title",
+  "section",
+  "section title",
+  "slide title",
+  "untitled",
+  "untitled deck",
+  "your name",
+]);
+
+/**
+ * Generated deck ids should never become user-facing titles. Keep this
+ * deliberately narrow so normal titles with spaces and punctuation remain
+ * valid, while catching opaque mixed-case tokens such as H3sVsnns-TEVUOpz9w.
+ */
+const OPAQUE_DECK_TITLE_PATTERN =
+  /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[A-Za-z0-9_-]{12,64}$/;
+
+export const DEFAULT_DECK_TITLE = "Untitled Deck";
+
+export function isOpaqueDeckTitle(value: unknown): value is string {
+  return (
+    typeof value === "string" && OPAQUE_DECK_TITLE_PATTERN.test(value.trim())
+  );
+}
+
+export function isGeneratedDeckTitle(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const title = value.trim();
+  return (
+    GENERATED_TITLE_PLACEHOLDERS.has(title.toLowerCase()) ||
+    isOpaqueDeckTitle(title)
+  );
+}
+
+function decodeHtmlEntities(value: string): string {
+  const decodeCodePoint = (raw: string, radix: number): string => {
+    const codePoint = Number.parseInt(raw, radix);
+    return Number.isNaN(codePoint) || codePoint > 0x10ffff
+      ? ""
+      : String.fromCodePoint(codePoint);
+  };
+
+  return value
+    .replace(/ /gi, " ")
+    .replace(/&/gi, "&")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&quot;/gi, '"')
+    .replace(/(?:&#39;|&apos;)/gi, "'")
+    .replace(/&#x([0-9a-f]+);?/gi, (_, hex: string) => decodeCodePoint(hex, 16))
+    .replace(/&#(\d+);?/g, (_, digits: string) => decodeCodePoint(digits, 10));
+}
+
+function plainText(value: string): string {
+  return decodeHtmlEntities(
+    value.replace(/<br\s*\/?>/gi, " ").replace(/<[^>]+>/g, " "),
+  )
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function usableCandidate(value: string): string | null {
+  const candidate = plainText(value).replace(/^[•●▪‣\-\s]+/, "");
+  if (!candidate || candidate.length > 140) return null;
+  if (GENERATED_TITLE_PLACEHOLDERS.has(candidate.toLowerCase())) return null;
+  return candidate;
+}
+
+/**
+ * Recover a deck title from the largest title-like text in its first slide.
+ * This is intentionally HTML-string based because the action runs on the
+ * server without a browser DOM.
+ */
+export function deriveDeckTitleFromSlideContent(
+  content: unknown,
+): string | null {
+  if (typeof content !== "string" || !content.trim()) return null;
+
+  const candidates: Array<{ score: number; text: string }> = [];
+  const headingPattern = /<(h[1-6])\b[^>]*>([\s\S]*?)<\/\1>/gi;
+  for (const match of content.matchAll(headingPattern)) {
+    const text = usableCandidate(match[2] ?? "");
+    if (text) {
+      const level = Number.parseInt(match[1].slice(1), 10);
+      candidates.push({ score: 1000 - level * 10, text });
+    }
+  }
+
+  const styledTextPattern =
+    /<([a-z][\w:-]*)\b[^>]*\bstyle\s*=\s*(["'])([\s\S]*?)\2[^>]*>([\s\S]*?)<\/\1>/gi;
+  for (const match of content.matchAll(styledTextPattern)) {
+    const fontSize = Number.parseFloat(
+      match[3]?.match(/(?:^|;)\s*font-size\s*:\s*([\d.]+)px/i)?.[1] ?? "0",
+    );
+    if (fontSize < 28) continue;
+    const text = usableCandidate(match[4] ?? "");
+    if (text) candidates.push({ score: fontSize, text });
+  }
+
+  return candidates.sort((a, b) => b.score - a.score)[0]?.text ?? null;
+}
+
+/**
+ * Return a human-readable replacement only when the requested title is a
+ * generated placeholder or opaque id. A meaningful existing title wins when
+ * a stale full-payload save tries to replace it with a generated value.
+ */
+export function repairGeneratedDeckTitle(
+  requestedTitle: unknown,
+  firstSlideContent: unknown,
+  existingTitle?: unknown,
+): string | null {
+  if (!isGeneratedDeckTitle(requestedTitle)) return null;
+
+  return (
+    deriveDeckTitleFromSlideContent(firstSlideContent) ??
+    (typeof existingTitle === "string" &&
+    existingTitle.trim() &&
+    !isGeneratedDeckTitle(existingTitle)
+      ? existingTitle
+      : null)
+  );
+}
+
+export function assertHumanReadableDeckTitle(title: string): void {
+  if (isOpaqueDeckTitle(title)) {
+    throw new Error(
+      "Deck title must be a concise, human-readable title; generated ids are not valid titles.",
+    );
+  }
+}