@agent-native/core-corpus 0.213.1 → 0.216.0

package/corpus/templates/slides-2/shared/design-system-validation.ts

@@ -0,0 +1,88 @@
+const REQUIRED_COLOR_KEYS = [
+  "primary",
+  "secondary",
+  "accent",
+  "background",
+  "surface",
+  "text",
+  "textMuted",
+];
+
+const REQUIRED_TYPOGRAPHY_KEYS = [
+  "headingFont",
+  "bodyFont",
+  "headingWeight",
+  "bodyWeight",
+];
+
+export function missingDesignSystemDataFields(value: unknown): string[] {
+  const missing: string[] = [];
+  const record =
+    value && typeof value === "object"
+      ? (value as Record<string, unknown>)
+      : {};
+
+  const colors =
+    record.colors && typeof record.colors === "object"
+      ? (record.colors as Record<string, unknown>)
+      : null;
+  if (!colors) {
+    missing.push("colors");
+  } else {
+    for (const key of REQUIRED_COLOR_KEYS) {
+      if (typeof colors[key] !== "string" || !colors[key]) {
+        missing.push(`colors.${key}`);
+      }
+    }
+  }
+
+  const typography =
+    record.typography && typeof record.typography === "object"
+      ? (record.typography as Record<string, unknown>)
+      : null;
+  if (!typography) {
+    missing.push("typography");
+  } else {
+    for (const key of REQUIRED_TYPOGRAPHY_KEYS) {
+      if (typeof typography[key] !== "string" || !typography[key]) {
+        missing.push(`typography.${key}`);
+      }
+    }
+  }
+
+  return missing;
+}
+
+export type DesignSystemIndexingStatus = "ready" | "indexing" | "unavailable";
+
+export function getDesignSystemIndexingStatus(
+  data: unknown,
+): DesignSystemIndexingStatus {
+  const record =
+    data && typeof data === "object" ? (data as Record<string, unknown>) : null;
+  if (!record || record.source !== "builder") return "ready";
+
+  const hasColors = record.colors && typeof record.colors === "object";
+  const hasTypography =
+    record.typography && typeof record.typography === "object";
+  const docCount = typeof record.docCount === "number" ? record.docCount : 0;
+  const hasTokens =
+    record.tokenValues &&
+    typeof record.tokenValues === "object" &&
+    Object.keys(record.tokenValues as Record<string, unknown>).length > 0;
+
+  if (hasColors || hasTypography || docCount > 0 || hasTokens) return "ready";
+  if (record.warning) return "unavailable";
+  return "indexing";
+}
+
+export function parseDesignSystemIndexingStatus(
+  data: string | null | undefined,
+): DesignSystemIndexingStatus {
+  if (!data) return "ready";
+  try {
+    return getDesignSystemIndexingStatus(JSON.parse(data));
+  } catch {
+    return "unavailable";
+  }
+}

package/corpus/templates/slides-2/shared/editor-control.ts

@@ -0,0 +1,120 @@
+import { z } from "zod";
+
+export const SLIDE_EDITOR_STATUS_KEY = "slide-editor-status";
+export const SLIDE_EDITOR_COMMAND_KEY = "slide-editor-command";
+
+const identifierSchema = z.string().min(1).max(128);
+const sourceHashSchema = z.string().regex(/^[a-f0-9]{64}$/);
+
+export const slideEditorStatusSchema = z
+  .object({
+    protocolVersion: z.literal(1),
+    deckId: identifierSchema,
+    slideId: identifierSchema,
+    editorSessionId: identifierSchema,
+    historyVersion: z.number().int().nonnegative(),
+    sourceRevision: z.number().int().positive(),
+    sourceHash: sourceHashSchema,
+    hasPendingEdits: z.boolean(),
+    canUndo: z.boolean(),
+    canRedo: z.boolean(),
+    canSave: z.boolean(),
+  })
+  .strict();
+
+export type SlideEditorStatus = z.infer<typeof slideEditorStatusSchema>;
+
+export const slideEditorCommandSchema = z
+  .object({
+    protocolVersion: z.literal(1),
+    commandId: z.string().regex(/^[A-Za-z0-9_-]{8,128}$/),
+    operation: z.enum(["undo", "redo", "save"]),
+    deckId: identifierSchema,
+    slideId: identifierSchema,
+    editorSessionId: identifierSchema,
+    historyVersion: z.number().int().nonnegative(),
+    sourceRevision: z.number().int().positive(),
+    sourceHash: sourceHashSchema,
+    status: z.enum(["pending", "applied", "rejected"]),
+    completedAt: z.number().int().nonnegative().optional(),
+    failureCode: z
+      .enum(["stale_editor_state", "command_unavailable", "command_failed"])
+      .optional(),
+  })
+  .strict();
+
+export type SlideEditorCommand = z.infer<typeof slideEditorCommandSchema>;
+
+export function isSlideEditorOperationAvailable(
+  status: SlideEditorStatus,
+  operation: SlideEditorCommand["operation"],
+): boolean {
+  switch (operation) {
+    case "undo":
+      return status.canUndo;
+    case "redo":
+      return status.canRedo;
+    case "save":
+      return status.hasPendingEdits && status.canSave;
+  }
+}
+
+export function slideEditorCommandMatchesEditorState(
+  commandValue: unknown,
+  status: SlideEditorStatus,
+  editorState: {
+    deckId: string;
+    slideId: string;
+    editorSessionId: string;
+    historyVersion: number;
+    sourceRevision: number;
+    sourceHash: string;
+  },
+): commandValue is SlideEditorCommand {
+  const parsed = slideEditorCommandSchema.safeParse(commandValue);
+  if (!parsed.success || parsed.data.status !== "pending") return false;
+  const command = parsed.data;
+  return (
+    slideEditorCommandMatchesStatus(command, status) &&
+    command.deckId === editorState.deckId &&
+    command.slideId === editorState.slideId &&
+    command.editorSessionId === editorState.editorSessionId &&
+    command.historyVersion === editorState.historyVersion &&
+    command.sourceRevision === editorState.sourceRevision &&
+    command.sourceHash === editorState.sourceHash
+  );
+}
+
+export function slideEditorCommandMatchesStatus(
+  commandValue: unknown,
+  status: SlideEditorStatus,
+): commandValue is SlideEditorCommand {
+  const parsed = slideEditorCommandSchema.safeParse(commandValue);
+  if (!parsed.success || parsed.data.status !== "pending") return false;
+  const command = parsed.data;
+  return (
+    command.deckId === status.deckId &&
+    command.slideId === status.slideId &&
+    command.editorSessionId === status.editorSessionId &&
+    command.historyVersion === status.historyVersion &&
+    command.sourceRevision === status.sourceRevision &&
+    command.sourceHash === status.sourceHash
+  );
+}
+
+export function completeSlideEditorCommand(
+  command: SlideEditorCommand,
+  result:
+    | { status: "applied" }
+    | {
+        status: "rejected";
+        failureCode: NonNullable<SlideEditorCommand["failureCode"]>;
+      },
+  completedAt = Date.now(),
+): SlideEditorCommand {
+  return slideEditorCommandSchema.parse({
+    ...command,
+    ...result,
+    completedAt,
+  });
+}

package/corpus/templates/slides-2/shared/generation-timing.ts

@@ -0,0 +1,19 @@
+export function generationTimingFields(
+  startedAt: number | undefined,
+  endedAt: number,
+): {
+  started_at_ms?: number;
+  ended_at_ms: number;
+  duration_ms?: number;
+  duration_error?: "clock_skew";
+} {
+  if (startedAt === undefined) return { ended_at_ms: endedAt };
+  const durationMs = endedAt - startedAt;
+  return {
+    started_at_ms: startedAt,
+    ended_at_ms: endedAt,
+    ...(durationMs >= 0
+      ? { duration_ms: durationMs }
+      : { duration_error: "clock_skew" }),
+  };
+}

package/corpus/templates/slides-2/shared/google-docs.ts

@@ -0,0 +1,69 @@
+const GOOGLE_DOC_ID_RE = /^[a-zA-Z0-9_-]{20,}$/;
+const GOOGLE_SLIDES_ID_RE = /^[a-zA-Z0-9_-]+$/;
+
+export function extractGoogleDocId(input: string): string | null {
+  const trimmed = input.trim();
+  if (!trimmed) return null;
+  if (GOOGLE_DOC_ID_RE.test(trimmed)) return trimmed;
+
+  let url: URL;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    // coercion-ok: an input that is neither a document ID nor a URL has no extractable ID.
+    return null;
+  }
+
+  if (!/(\.|^)google\.com$/i.test(url.hostname)) return null;
+
+  const standardMatch = url.pathname.match(
+    /\/document\/(?:u\/\d+\/)?d\/([a-zA-Z0-9_-]+)/,
+  );
+  if (standardMatch) return standardMatch[1];
+
+  const idParam = url.searchParams.get("id");
+  return idParam && GOOGLE_DOC_ID_RE.test(idParam) ? idParam : null;
+}
+
+export function extractGoogleDocUrls(text: string): string[] {
+  const urls = new Set<string>();
+  const pattern = /https:\/\/docs\.google\.com\/document\/[^\s<>"'`),\]]+/gi;
+  for (const match of text.matchAll(pattern)) {
+    const url = match[0].replace(/[.,;:!?]+$/, "");
+    if (extractGoogleDocId(url)) urls.add(url);
+  }
+  return [...urls];
+}
+
+export function extractGoogleSlidesUrls(text: string): string[] {
+  const urls = new Set<string>();
+  const pattern =
+    /https:\/\/docs\.google\.com\/presentation(?:\/u\/\d+)?\/d\/[^\s<>"'`),\]]+/gi;
+  for (const match of text.matchAll(pattern)) {
+    const url = match[0].replace(/[.,;:!?]+$/, "");
+    let parsed: URL;
+    try {
+      parsed = new URL(url);
+    } catch {
+      continue;
+    }
+
+    if (!/(\.|^)google\.com$/i.test(parsed.hostname)) continue;
+
+    const presentationMatch = parsed.pathname.match(
+      /\/presentation(?:\/u\/\d+)?\/d\/([a-zA-Z0-9_-]+)/,
+    );
+    if (presentationMatch && GOOGLE_SLIDES_ID_RE.test(presentationMatch[1])) {
+      urls.add(url);
+    }
+  }
+  return [...urls];
+}
+
+export function normalizeGoogleDocText(text: string): string {
+  return text
+    .replace(/\u0000/g, "")
+    .replace(/\r\n?/g, "\n")
+    .replace(/[ \t]+\n/g, "\n")
+    .trim();
+}

package/corpus/templates/slides-2/shared/labs.ts

@@ -0,0 +1,10 @@
+import { defineLab, defineLabs } from "@agent-native/core/labs/registry";
+
+export const SLIDES_LAYOUT_OVERFLOW_WARNING = defineLab({
+  key: "slides.layout-overflow-warning",
+  displayName: "Layout overflow warning",
+  description: "Show the layout overflow warning in the editor.",
+  keywords: "slides layout overflow warning canvas fit",
+});
+
+export const SLIDES_LABS = defineLabs([SLIDES_LAYOUT_OVERFLOW_WARNING]);

package/corpus/templates/slides-2/shared/overview-navigation.ts

@@ -0,0 +1,34 @@
+export function overviewFocusNavigationIndex(
+  focusedIndex: number,
+  slideCount: number,
+  key: string,
+  columns: number,
+): number | null {
+  if (
+    !Number.isInteger(focusedIndex) ||
+    !Number.isInteger(slideCount) ||
+    !Number.isInteger(columns) ||
+    focusedIndex < 0 ||
+    focusedIndex >= slideCount ||
+    columns < 1
+  ) {
+    return null;
+  }
+
+  if (key === "Home") return 0;
+  if (key === "End") return slideCount - 1;
+
+  const offset =
+    key === "ArrowRight"
+      ? 1
+      : key === "ArrowLeft"
+        ? -1
+        : key === "ArrowDown"
+          ? columns
+          : key === "ArrowUp"
+            ? -columns
+            : null;
+  if (offset === null) return null;
+
+  return Math.max(0, Math.min(slideCount - 1, focusedIndex + offset));
+}

package/corpus/templates/slides-2/shared/ownership.ts

@@ -0,0 +1,6 @@
+export function normalizeOwnerEmail(
+  email: string | null | undefined,
+): string | null {
+  const normalized = email?.trim().toLowerCase();
+  return normalized || null;
+}

package/corpus/templates/slides-2/shared/pdf-sidecar.ts

@@ -0,0 +1,130 @@
+import type { AnimationTrigger } from "./api";
+import {
+  normalizeSlideTransition,
+  SLIDE_TRANSITION_INPUTS,
+  SLIDE_TRANSITION_SPEED,
+  type SlideTransitionType,
+} from "./slide-transitions";
+
+export const SLIDES_PDF_SIDECAR_NAMESPACE =
+  "https://agent-native.com/ns/slides-deck/1.0/";
+
+export interface SlidesPdfSidecarAnimation {
+  id: string;
+  elementIndex: number;
+  elementPath?: number[];
+  trigger?: AnimationTrigger;
+  type: "appear" | "fade" | "slide-up" | "zoom";
+}
+
+/**
+ * One slide, carried whole — with one deliberate omission. Everything the
+ * editor stores about how a slide *looks* travels, because dropping
+ * animations, transitions, or an Excalidraw scene would make the restore
+ * another partial reconstruction. Speaker notes do not: a PDF is the artifact
+ * people forward, and notes are private commentary the page never shows.
+ * `toSharedDeckSlide` already blanks them on every public surface, and
+ * PowerPoint and Google Slides both leave them out of a PDF export.
+ */
+export interface SlidesPdfSidecarSlide {
+  content: string;
+  layout?: string;
+  background?: string;
+  imageUrl?: string;
+  excalidrawData?: string;
+  transition?: SlideTransitionType;
+  transitionSpeed?: number;
+  splitByParagraph?: boolean;
+  skipped?: boolean;
+  animations?: SlidesPdfSidecarAnimation[];
+}
+
+export interface SlidesPdfSidecar {
+  v: 1;
+  title?: string;
+  aspectRatio?: string;
+  slides: SlidesPdfSidecarSlide[];
+}
+
+export const SLIDES_PDF_SIDECAR_MAX_JSON_BYTES = 4_000_000;
+
+export const SLIDES_PDF_SIDECAR_MAX_BASE64_BYTES = Math.ceil(
+  (SLIDES_PDF_SIDECAR_MAX_JSON_BYTES * 4) / 3 + 4,
+);
+
+function isOptionalString(value: unknown): boolean {
+  return value === undefined || typeof value === "string";
+}
+
+const ANIMATION_TYPES = ["appear", "fade", "slide-up", "zoom"] as const;
+
+function isAnimationList(value: unknown): boolean {
+  if (value === undefined) return true;
+  if (!Array.isArray(value)) return false;
+  return value.every((entry) => {
+    if (typeof entry !== "object" || entry === null) return false;
+    const animation = entry as SlidesPdfSidecarAnimation;
+    if (typeof animation.id !== "string") return false;
+    if (!Number.isInteger(animation.elementIndex)) return false;
+    if (
+      animation.elementPath !== undefined &&
+      !(
+        Array.isArray(animation.elementPath) &&
+        animation.elementPath.every((step) => Number.isInteger(step))
+      )
+    ) {
+      return false;
+    }
+    return (ANIMATION_TYPES as readonly string[]).includes(animation.type);
+  });
+}
+
+function isOptionalTransitionSpeed(value: unknown): boolean {
+  if (value === undefined) return true;
+  return (
+    typeof value === "number" &&
+    Number.isInteger(value) &&
+    value >= SLIDE_TRANSITION_SPEED.min &&
+    value <= SLIDE_TRANSITION_SPEED.max
+  );
+}
+
+// Accepts legacy transition names (instant, slide, zoom) from PDFs exported
+// before the catalog existed. On success those are rewritten to canonical
+// values in place, so a guarded value always carries SlideTransitionType.
+export function isSlidesPdfSidecar(value: unknown): value is SlidesPdfSidecar {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Partial<SlidesPdfSidecar>;
+  if (candidate.v !== 1) return false;
+  if (!isOptionalString(candidate.title)) return false;
+  if (!isOptionalString(candidate.aspectRatio)) return false;
+  if (!Array.isArray(candidate.slides)) return false;
+  const valid = candidate.slides.every((entry) => {
+    if (typeof entry !== "object" || entry === null) return false;
+    const slide = entry as SlidesPdfSidecarSlide;
+    if (typeof slide.content !== "string") return false;
+    for (const flag of [slide.splitByParagraph, slide.skipped]) {
+      if (flag !== undefined && typeof flag !== "boolean") return false;
+    }
+    if (!isAnimationList(slide.animations)) return false;
+    return (
+      isOptionalString(slide.layout) &&
+      isOptionalString(slide.background) &&
+      isOptionalString(slide.imageUrl) &&
+      isOptionalString(slide.excalidrawData) &&
+      (slide.transition === undefined ||
+        (SLIDE_TRANSITION_INPUTS as readonly unknown[]).includes(
+          slide.transition,
+        )) &&
+      isOptionalTransitionSpeed(slide.transitionSpeed)
+    );
+  });
+  if (!valid) return false;
+
+  for (const slide of candidate.slides) {
+    if (slide.transition !== undefined) {
+      slide.transition = normalizeSlideTransition(slide.transition);
+    }
+  }
+  return true;
+}

package/corpus/templates/slides-2/shared/presenter-control.ts

@@ -0,0 +1,111 @@
+import { z } from "zod";
+
+const deckIdSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(512)
+  .describe("Deck ID for the active presentation");
+
+export const presenterControlInputSchema = z.discriminatedUnion("operation", [
+  z.object({
+    deckId: deckIdSchema,
+    operation: z.literal("next").describe("Advance to the next step or slide"),
+  }),
+  z.object({
+    deckId: deckIdSchema,
+    operation: z
+      .literal("previous")
+      .describe("Return to the previous step or slide"),
+  }),
+  z.object({
+    deckId: deckIdSchema,
+    operation: z
+      .literal("goto")
+      .describe("Jump to a slide by its 1-based UI slide number"),
+    slideNumber: z
+      .number()
+      .int()
+      .min(1)
+      .describe(
+        "1-based slide number to show, from 1 through the deck's current slide count",
+      ),
+  }),
+  z.object({
+    deckId: deckIdSchema,
+    operation: z
+      .literal("blackout")
+      .describe("Toggle a black or white overlay on the projected slide"),
+    mode: z.enum(["black", "white"]).describe("Overlay color to toggle"),
+  }),
+  z.object({
+    deckId: deckIdSchema,
+    operation: z
+      .literal("switch-deck")
+      .describe("Switch the open presenter console to another accessible deck"),
+    targetDeckId: z
+      .string()
+      .trim()
+      .min(1)
+      .max(512)
+      .describe("Deck ID to open; requires viewer access"),
+  }),
+]);
+
+const commandMetadataSchema = {
+  commandId: z.string().uuid(),
+  issuedAt: z.number().int().nonnegative(),
+};
+
+export const presenterControlCommandSchema = z.discriminatedUnion("operation", [
+  z.object({
+    ...commandMetadataSchema,
+    deckId: deckIdSchema,
+    operation: z.literal("next"),
+  }),
+  z.object({
+    ...commandMetadataSchema,
+    deckId: deckIdSchema,
+    operation: z.literal("previous"),
+  }),
+  z.object({
+    ...commandMetadataSchema,
+    deckId: deckIdSchema,
+    operation: z.literal("goto"),
+    slideNumber: z.number().int().min(1),
+  }),
+  z.object({
+    ...commandMetadataSchema,
+    deckId: deckIdSchema,
+    operation: z.literal("blackout"),
+    mode: z.enum(["black", "white"]),
+  }),
+  z.object({
+    ...commandMetadataSchema,
+    deckId: deckIdSchema,
+    operation: z.literal("switch-deck"),
+    targetDeckId: z.string().trim().min(1).max(512),
+  }),
+]);
+
+export const presenterControlQueueSchema = z.object({
+  commands: z.array(presenterControlCommandSchema).max(100),
+});
+
+export type PresenterControlInput = z.infer<typeof presenterControlInputSchema>;
+export type PresenterControlCommand = z.infer<
+  typeof presenterControlCommandSchema
+>;
+export type PresenterControlQueue = z.infer<typeof presenterControlQueueSchema>;
+
+export const PRESENTER_CONTROL_QUEUE_LIMIT = 100;
+export const PRESENTER_CONTROL_COMMAND_TTL_MS = 60_000;
+
+export function isPresenterControlCommandFresh(
+  command: PresenterControlCommand,
+  now = Date.now(),
+): boolean {
+  const age = now - command.issuedAt;
+  // The action and console use server and browser clocks, respectively.
+  return Math.abs(age) <= PRESENTER_CONTROL_COMMAND_TTL_MS;
+}

package/corpus/templates/slides-2/shared/representative-slide.ts

@@ -0,0 +1,89 @@
+import {
+  formatHtmlStyleSummary,
+  summarizeHtmlStyles,
+} from "@agent-native/core/shared";
+
+import { backgroundCssValue } from "./slide-background.js";
+
+export interface StyledSlide {
+  id: string;
+  layout?: string;
+  content?: string;
+  background?: string;
+}
+
+export function slideStyleFragment(slide: StyledSlide): string {
+  const fill = slide.background ? backgroundCssValue(slide.background) : null;
+  const html = typeof slide.content === "string" ? slide.content : "";
+  return fill ? `<div style="background: ${fill}">${html}</div>` : html;
+}
+
+export function pickRepresentativeSlide(
+  slides: StyledSlide[],
+  currentIndex: number,
+): number | null {
+  if (slides.length < 2) return null;
+  const fragments = slides.map((slide, index) => ({
+    label: `slide ${index + 1}`,
+    html: slideStyleFragment(slide),
+  }));
+  const deck = summarizeHtmlStyles(fragments);
+  const shared = (values: { value: string; fragments: number }[]) =>
+    values[0] && values[0].fragments > 1 ? values[0].value : undefined;
+  const majorityBackground = shared(deck.backgrounds);
+  const majorityText = shared(deck.textColors);
+  const carriesMajority = (index: number): boolean => {
+    const own = summarizeHtmlStyles([fragments[index]!]);
+    return (
+      (!majorityBackground ||
+        own.backgrounds.some((entry) => entry.value === majorityBackground)) &&
+      (!majorityText ||
+        own.textColors.some((entry) => entry.value === majorityText))
+    );
+  };
+  const others = slides
+    .map((_, index) => index)
+    .filter((index) => index !== currentIndex);
+  const currentLayout = slides[currentIndex]?.layout;
+  const sameLayout = others.filter(
+    (index) =>
+      currentLayout !== undefined && slides[index]!.layout === currentLayout,
+  );
+  return (
+    sameLayout.find(carriesMajority) ??
+    others.find(carriesMajority) ??
+    sameLayout[0] ??
+    others[0] ??
+    null
+  );
+}
+
+export function summarizeDeckStyle(
+  slides: StyledSlide[],
+  currentIndex = -1,
+): {
+  deckStyle: string[];
+  representativeSlideIndex: number | null;
+  representativeSlideId: string | null;
+} {
+  const deckStyle = formatHtmlStyleSummary(
+    summarizeHtmlStyles(
+      slides
+        .map((slide, index) => ({
+          label: `slide ${index + 1}`,
+          html: slideStyleFragment(slide),
+        }))
+        .filter((fragment) => fragment.html.length > 0),
+    ),
+    { noun: "slide" },
+  );
+  const representativeSlideIndex = pickRepresentativeSlide(
+    slides,
+    currentIndex,
+  );
+  const representativeSlideId =
+    representativeSlideIndex !== null
+      ? (slides[representativeSlideIndex]?.id ?? null)
+      : null;
+  return { deckStyle, representativeSlideIndex, representativeSlideId };
+}