@agent-native/creative-context 0.1.0 → 0.3.0

package/src/client/source-config.spec.ts

@@ -2,28 +2,22 @@ import { describe, expect, it } from "vitest";
 
 import {
   buildCreativeContextSourceConfig,
+  mergeRecommendationSelection,
   parseFigmaRecommendationBoundary,
   selectRenderableLayoutThumbnails,
 } from "./CreativeContextPanel.js";
 
 describe("creative context source configuration", () => {
-  it("keeps Google Slides imports inside an explicit folder or shared drive", () => {
+  it("keeps Google Slides imports inside explicit presentation boundaries", () => {
     expect(
       buildCreativeContextSourceConfig(
         "google-slides",
-        "https://drive.google.com/drive/folders/folder-1",
+        "https://docs.google.com/presentation/d/deck-1/edit\ndeck-2",
         [],
       ),
     ).toEqual({
-      folderUrl: "https://drive.google.com/drive/folders/folder-1",
+      presentationIds: ["deck-1", "deck-2"],
     });
-    expect(
-      buildCreativeContextSourceConfig(
-        "google-slides",
-        "shared-drive:drive-1",
-        [],
-      ),
-    ).toEqual({ sharedDriveId: "drive-1" });
   });
 
   it("turns confirmed provider recommendations into exact import boundaries", () => {
@@ -149,4 +143,24 @@ describe("creative context source configuration", () => {
       ]).map((thumbnail) => thumbnail.itemVersionId),
     ).toEqual(["v1", "v3", "v4"]);
   });
+
+  it("keeps explicit deck deselections while selecting newly discovered decks", () => {
+    expect(
+      mergeRecommendationSelection(
+        new Set(["still-selected"]),
+        new Set(["still-selected", "unchecked", "new-deck"]),
+        new Set(["still-selected", "unchecked"]),
+      ),
+    ).toEqual(new Set(["still-selected", "new-deck"]));
+  });
+
+  it("drops recommendations that are no longer available", () => {
+    expect(
+      mergeRecommendationSelection(
+        new Set(["available", "removed"]),
+        new Set(["available"]),
+        new Set(["available", "removed"]),
+      ),
+    ).toEqual(new Set(["available"]));
+  });
 });

package/src/connectors/google-slides.ts

@@ -37,8 +37,7 @@ import type {
 
 const SLIDES_MIME_TYPE = "application/vnd.google-apps.presentation";
 export const GOOGLE_SLIDES_CONTEXT_OAUTH_SCOPES = [
-  "https://www.googleapis.com/auth/drive.metadata.readonly",
-  "https://www.googleapis.com/auth/presentations.readonly",
+  "https://www.googleapis.com/auth/drive.file",
 ] as const;
 
 export class GoogleSlidesContextConnector implements ContextImportConnector {

package/src/connectors/normalize.spec.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  assertContextItemSqlTextLimits,
+  MAX_METADATA_BYTES,
+  MAX_MEDIA_LOCATOR_BYTES,
+  MAX_MEDIA_TEXT_BYTES,
+  MAX_NATIVE_CONTENT_BYTES,
+  MAX_SEARCHABLE_CONTENT_BYTES,
+  MAX_SUMMARY_BYTES,
+  normalizeContextItem,
+} from "./normalize.js";
+
+describe("normalizeContextItem SQL text limits", () => {
+  it("bounds emoji content and summaries by UTF-8 bytes without splitting code points", () => {
+    const item = normalizeContextItem({
+      externalId: "emoji",
+      kind: "document",
+      title: "Emoji",
+      content: "🙂".repeat(20_000),
+      summary: "🙂".repeat(3_000),
+    });
+
+    expect(Buffer.byteLength(item.content, "utf8")).toBe(
+      MAX_SEARCHABLE_CONTENT_BYTES,
+    );
+    expect(Array.from(item.content)).toHaveLength(
+      MAX_SEARCHABLE_CONTENT_BYTES / 4,
+    );
+    expect(Buffer.byteLength(item.summary!, "utf8")).toBe(MAX_SUMMARY_BYTES);
+    expect(Array.from(item.summary!)).toHaveLength(MAX_SUMMARY_BYTES / 4);
+    expect(item.content).not.toContain("�");
+    expect(item.summary).not.toContain("�");
+  });
+
+  it("uses the largest complete CJK prefix that fits the UTF-8 byte budget", () => {
+    const item = normalizeContextItem({
+      externalId: "cjk",
+      kind: "document",
+      title: "CJK",
+      content: "界".repeat(30_000),
+    });
+
+    const expectedCodePoints = Math.floor(MAX_SEARCHABLE_CONTENT_BYTES / 3);
+    expect(Array.from(item.content)).toHaveLength(expectedCodePoints);
+    expect(Buffer.byteLength(item.content, "utf8")).toBe(
+      expectedCodePoints * 3,
+    );
+    expect(Buffer.byteLength(item.content, "utf8")).toBeLessThanOrEqual(
+      MAX_SEARCHABLE_CONTENT_BYTES,
+    );
+  });
+
+  it("rejects oversized native HTML intact instead of truncating its markup", () => {
+    const html = `<div class="fmd-slide">${"界".repeat(MAX_NATIVE_CONTENT_BYTES / 3)}</div>`;
+
+    expect(() =>
+      normalizeContextItem({
+        externalId: "oversized-native",
+        kind: "google-slides-slide",
+        title: "Oversized native slide",
+        mimeType: "text/html",
+        content: html,
+        metadata: {
+          nativeArtifact: { app: "slides", format: "slides-html" },
+        },
+      }),
+    ).toThrow(/native content.*exceeds.*split the artifact/i);
+  });
+
+  it("rejects oversized structured metadata and media text before SQL writes", () => {
+    const oversizedMetadata = normalizeContextItem({
+      externalId: "oversized-metadata",
+      kind: "presentation",
+      title: "Oversized metadata",
+      content: "small",
+      metadata: { speakerNotes: "x".repeat(MAX_METADATA_BYTES) },
+    });
+    expect(() => assertContextItemSqlTextLimits(oversizedMetadata)).toThrow(
+      /item metadata.*exceeds.*private blob storage/i,
+    );
+
+    const oversizedMedia = normalizeContextItem({
+      externalId: "oversized-media",
+      kind: "presentation",
+      title: "Oversized media",
+      content: "small",
+      media: [
+        {
+          kind: "image",
+          url: "https://example.com/image.png",
+          ocrText: "x".repeat(MAX_MEDIA_TEXT_BYTES + 1),
+          metadata: { providerPayload: "small" },
+        },
+      ],
+    });
+    expect(() => assertContextItemSqlTextLimits(oversizedMedia)).toThrow(
+      /media OCR text.*exceeds.*private blob storage/i,
+    );
+
+    const oversizedProvenance = normalizeContextItem({
+      externalId: "oversized-provenance",
+      kind: "presentation",
+      title: "Oversized provenance",
+      content: "small",
+      provenance: { providerPayload: "x".repeat(MAX_METADATA_BYTES) },
+    });
+    expect(() => assertContextItemSqlTextLimits(oversizedProvenance)).toThrow(
+      /item provenance.*exceeds.*private blob storage/i,
+    );
+
+    const inlineDataUrl = normalizeContextItem({
+      externalId: "inline-media",
+      kind: "presentation",
+      title: "Inline media",
+      content: "small",
+      media: [
+        {
+          kind: "image",
+          url: "data:image/png;base64,AAAA",
+        },
+      ],
+    });
+    expect(() => assertContextItemSqlTextLimits(inlineDataUrl)).toThrow(
+      /media URL cannot be an inline data URL/i,
+    );
+
+    const oversizedLocator = normalizeContextItem({
+      externalId: "oversized-locator",
+      kind: "presentation",
+      title: "Oversized locator",
+      content: "small",
+      media: [
+        {
+          kind: "image",
+          url: `https://example.com/${"x".repeat(MAX_MEDIA_LOCATOR_BYTES)}`,
+        },
+      ],
+    });
+    expect(() => assertContextItemSqlTextLimits(oversizedLocator)).toThrow(
+      /media URL.*exceeds.*private blob storage/i,
+    );
+  });
+});

package/src/connectors/normalize.ts

@@ -11,6 +11,12 @@ import type {
 } from "../types.js";
 
 const DEFAULT_CHUNK_CHARS = 4_000;
+export const MAX_SEARCHABLE_CONTENT_BYTES = 64 * 1024;
+export const MAX_SUMMARY_BYTES = 8 * 1024;
+export const MAX_NATIVE_CONTENT_BYTES = 128 * 1024;
+export const MAX_METADATA_BYTES = 32 * 1024;
+export const MAX_MEDIA_TEXT_BYTES = 64 * 1024;
+export const MAX_MEDIA_LOCATOR_BYTES = 16 * 1024;
 
 export interface NormalizeContextItemInput {
   externalId: string;
@@ -56,13 +62,16 @@ export function normalizeContextItem(
     (input.mimeType === "text/html" &&
       (nativeArtifact?.format === "slides-html" ||
         nativeArtifact?.format === "design-html"));
-  const content = preserveContent
+  const candidateContent = preserveContent
     ? input.content.replace(/\r\n?/g, "\n").trim()
     : normalizeWhitespace(input.content);
+  const content = preserveContent
+    ? requireBoundedNativeContent(candidateContent)
+    : boundText(candidateContent, MAX_SEARCHABLE_CONTENT_BYTES);
   const summary = input.summary
-    ? normalizeWhitespace(input.summary)
+    ? boundText(normalizeWhitespace(input.summary), MAX_SUMMARY_BYTES)
     : undefined;
-  const chunks = input.chunks ?? chunkContextText(content);
+  const chunks = boundChunks(input.chunks ?? chunkContextText(content));
   const normalized = {
     externalId,
     kind: required(input.kind, "kind"),
@@ -98,6 +107,195 @@ export function normalizeContextItem(
   };
 }
 
+function boundText(value: string, maxBytes: number): string {
+  if (Buffer.byteLength(value, "utf8") <= maxBytes) return value;
+  let bytes = 0;
+  let endOffset = 0;
+  for (const codePoint of value) {
+    const codePointBytes = Buffer.byteLength(codePoint, "utf8");
+    if (bytes + codePointBytes > maxBytes) break;
+    bytes += codePointBytes;
+    endOffset += codePoint.length;
+  }
+  return value.slice(0, endOffset);
+}
+
+function requireBoundedNativeContent(value: string): string {
+  const bytes = Buffer.byteLength(value, "utf8");
+  if (bytes > MAX_NATIVE_CONTENT_BYTES) {
+    throw new Error(
+      `Creative context native content is ${bytes} bytes and exceeds the ${MAX_NATIVE_CONTENT_BYTES}-byte SQL inline limit; split the artifact or store it in private blob storage instead of truncating it`,
+    );
+  }
+  return value;
+}
+
+export function assertContextItemSqlTextLimits(
+  item: Pick<
+    NormalizedContextItem,
+    | "content"
+    | "summary"
+    | "mimeType"
+    | "provenance"
+    | "metadata"
+    | "chunks"
+    | "media"
+    | "edges"
+  >,
+): void {
+  const nativeArtifact = item.metadata?.nativeArtifact;
+  const isNativeContent =
+    item.mimeType === "text/html" &&
+    typeof nativeArtifact === "object" &&
+    nativeArtifact !== null &&
+    !Array.isArray(nativeArtifact) &&
+    ((nativeArtifact as Record<string, unknown>).format === "slides-html" ||
+      (nativeArtifact as Record<string, unknown>).format === "design-html");
+  const contentLimit = isNativeContent
+    ? MAX_NATIVE_CONTENT_BYTES
+    : MAX_SEARCHABLE_CONTENT_BYTES;
+  assertSqlTextLimit(
+    isNativeContent ? "native content" : "searchable content",
+    item.content,
+    contentLimit,
+    isNativeContent
+      ? "split the artifact or store it in private blob storage"
+      : "normalize or chunk the source before ingest",
+  );
+  if (item.summary) {
+    assertSqlTextLimit(
+      "summary",
+      item.summary,
+      MAX_SUMMARY_BYTES,
+      "normalize the summary before ingest",
+    );
+  }
+  assertJsonSqlTextLimit(
+    "item metadata",
+    item.metadata,
+    MAX_METADATA_BYTES,
+    "move raw payloads to private blob storage before ingest",
+  );
+  assertJsonSqlTextLimit(
+    "item provenance",
+    item.provenance,
+    MAX_METADATA_BYTES,
+    "move raw payloads to private blob storage before ingest",
+  );
+  let chunkBytes = 0;
+  for (const chunk of item.chunks ?? []) {
+    chunkBytes += Buffer.byteLength(chunk.text, "utf8");
+    if (chunkBytes > MAX_SEARCHABLE_CONTENT_BYTES) {
+      throw new Error(
+        `Creative context chunks exceed the ${MAX_SEARCHABLE_CONTENT_BYTES}-byte SQL text limit; normalize or split the chunks before ingest`,
+      );
+    }
+    assertJsonSqlTextLimit(
+      "chunk metadata",
+      chunk.metadata,
+      MAX_METADATA_BYTES,
+      "move raw payloads to private blob storage before ingest",
+    );
+  }
+  for (const media of item.media ?? []) {
+    for (const [label, value] of [
+      ["media alt text", media.altText],
+      ["media caption", media.caption],
+      ["media OCR text", media.ocrText],
+    ] as const) {
+      if (value) {
+        assertSqlTextLimit(
+          label,
+          value,
+          MAX_MEDIA_TEXT_BYTES,
+          "move raw payloads to private blob storage before ingest",
+        );
+      }
+    }
+    for (const [label, value] of [
+      ["media URL", media.url],
+      ["media storage key", media.storageKey],
+      ["media provenance URL", media.provenanceUrl],
+    ] as const) {
+      if (!value) continue;
+      if (value.trim().toLowerCase().startsWith("data:")) {
+        throw new Error(
+          `Creative context ${label} cannot be an inline data URL; store the payload in private blob storage instead`,
+        );
+      }
+      assertSqlTextLimit(
+        label,
+        value,
+        MAX_MEDIA_LOCATOR_BYTES,
+        "move raw payloads to private blob storage before ingest",
+      );
+    }
+    assertJsonSqlTextLimit(
+      "media metadata",
+      media.metadata,
+      MAX_METADATA_BYTES,
+      "move raw payloads to private blob storage before ingest",
+    );
+  }
+  for (const edge of item.edges ?? []) {
+    assertJsonSqlTextLimit(
+      "edge metadata",
+      edge.metadata,
+      MAX_METADATA_BYTES,
+      "move raw payloads to private blob storage before ingest",
+    );
+  }
+}
+
+function assertJsonSqlTextLimit(
+  label: string,
+  value: unknown,
+  maxBytes: number,
+  guidance: string,
+): void {
+  if (value === undefined) return;
+  const serialized = JSON.stringify(value);
+  if (serialized === undefined) return;
+  assertSqlTextLimit(label, serialized, maxBytes, guidance);
+}
+
+function assertSqlTextLimit(
+  label: string,
+  value: string,
+  maxBytes: number,
+  guidance: string,
+): void {
+  const bytes = Buffer.byteLength(value, "utf8");
+  if (bytes > maxBytes) {
+    throw new Error(
+      `Creative context ${label} is ${bytes} bytes and exceeds the ${maxBytes}-byte SQL text limit; ${guidance}`,
+    );
+  }
+}
+
+function boundChunks(
+  chunks: NormalizedContextChunk[],
+): NormalizedContextChunk[] {
+  let remaining = MAX_SEARCHABLE_CONTENT_BYTES;
+  return chunks.flatMap((chunk) => {
+    if (remaining <= 0) return [];
+    const text = boundText(chunk.text, remaining);
+    remaining -= Buffer.byteLength(text, "utf8");
+    return text
+      ? [
+          {
+            ...chunk,
+            text,
+            endOffset:
+              chunk.startOffset == null
+                ? chunk.endOffset
+                : chunk.startOffset + text.length,
+          },
+        ]
+      : [];
+  });
+}
+
 export function hashContextContent(value: unknown): string {
   return createHash("sha256").update(stableJson(value)).digest("hex");
 }

package/src/server/enrichment.spec.ts

@@ -0,0 +1,94 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  appendVersion: vi.fn(),
+  availableFamilies: vi.fn(),
+  getActiveEmbeddingSet: vi.fn(),
+  getCreativeContext: vi.fn(),
+  readMedia: vi.fn(),
+  fingerprintMedia: vi.fn(),
+  extractDominantColors: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/ingestion", () => ({
+  fingerprintMedia: mocks.fingerprintMedia,
+  extractDominantColors: mocks.extractDominantColors,
+}));
+
+vi.mock("../embeddings/providers.js", () => ({
+  availableEmbeddingFamilies: mocks.availableFamilies,
+}));
+
+vi.mock("../store/index.js", () => ({
+  appendMediaEnrichmentVersion: mocks.appendVersion,
+  getActiveEmbeddingSet: mocks.getActiveEmbeddingSet,
+  getCreativeContextItem: vi.fn(),
+  recordEmbeddingMetadata: vi.fn(),
+}));
+
+vi.mock("./context.js", () => ({
+  getCreativeContext: mocks.getCreativeContext,
+}));
+
+vi.mock("./media.js", () => ({
+  readCreativeContextMedia: mocks.readMedia,
+}));
+
+import { enrichCreativeContextMedia } from "./enrichment.js";
+
+describe("creative context media enrichment", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.readMedia.mockResolvedValue({
+      data: new Uint8Array([1, 2, 3]),
+      mimeType: "image/png",
+      itemId: "item-1",
+      itemVersionId: "version-1",
+      mediaId: "media-1",
+      media: {
+        caption: null,
+        ocrText: null,
+      },
+    });
+    mocks.fingerprintMedia.mockReturnValue({ sha256: "image-hash" });
+    mocks.extractDominantColors.mockResolvedValue(["#663399"]);
+    mocks.availableFamilies.mockResolvedValue([]);
+    mocks.getActiveEmbeddingSet.mockResolvedValue(null);
+    mocks.appendVersion.mockResolvedValue({
+      itemId: "item-1",
+      itemVersionId: "version-2",
+      mediaId: "media-2",
+      appended: true,
+    });
+    mocks.getCreativeContext.mockReturnValue({
+      vectorAdapter: null,
+      projections: undefined,
+      enrichment: {
+        captionImage: vi.fn(async () => "A purple dashboard"),
+        ocrImage: vi.fn(async () => "Ship faster"),
+      },
+    });
+  });
+
+  it("writes enrichment as a new immutable version and returns its ids", async () => {
+    await expect(
+      enrichCreativeContextMedia({ mediaId: "media-1" }),
+    ).resolves.toMatchObject({
+      mediaId: "media-2",
+      itemId: "item-1",
+      itemVersionId: "version-2",
+      versionAppended: true,
+      caption: "A purple dashboard",
+      ocrText: "Ship faster",
+      palette: ["#663399"],
+    });
+    expect(mocks.appendVersion).toHaveBeenCalledWith({
+      mediaId: "media-1",
+      palette: ["#663399"],
+      contentHash: "image-hash",
+      caption: "A purple dashboard",
+      captionStatus: "complete",
+      ocrText: "Ship faster",
+    });
+  });
+});

package/src/server/enrichment.ts

@@ -8,6 +8,7 @@ import { eq } from "drizzle-orm";
 
 import { availableEmbeddingFamilies } from "../embeddings/providers.js";
 import {
+  appendMediaEnrichmentVersion,
   getActiveEmbeddingSet,
   getCreativeContextItem,
   recordEmbeddingMetadata,
@@ -59,7 +60,7 @@ export async function enrichCreativeContextMedia(input: {
       "Creative context media enrichment supports PNG, JPEG, WebP, or GIF images.",
     );
   }
-  const { getDb, schema, vectorAdapter, enrichment } = getCreativeContext();
+  const { vectorAdapter, enrichment } = getCreativeContext();
   const fingerprint = fingerprintMedia(loaded.data, loaded.mimeType);
   const palette = await extractDominantColors(
     loaded.data,
@@ -81,20 +82,21 @@ export async function enrichCreativeContextMedia(input: {
       mediaId: input.mediaId,
     }) ?? Promise.resolve(null),
   ]);
-  await getDb()
-    .update(schema.contextMedia)
-    .set({
-      palette: JSON.stringify(palette),
-      contentHash: fingerprint.sha256,
-      caption: caption ?? loaded.media?.caption ?? null,
-      captionStatus: enrichment?.captionImage
-        ? caption
-          ? "complete"
-          : "failed"
-        : "pending",
-      ocrText: ocrText ?? loaded.media?.ocrText ?? null,
-    })
-    .where(eq(schema.contextMedia.id, input.mediaId));
+  const nextCaption = caption ?? loaded.media?.caption ?? null;
+  const nextCaptionStatus = enrichment?.captionImage
+    ? caption
+      ? ("complete" as const)
+      : ("failed" as const)
+    : ("pending" as const);
+  const nextOcrText = ocrText ?? loaded.media?.ocrText ?? null;
+  const snapshot = await appendMediaEnrichmentVersion({
+    mediaId: input.mediaId,
+    palette,
+    contentHash: fingerprint.sha256,
+    caption: nextCaption,
+    captionStatus: nextCaptionStatus,
+    ocrText: nextOcrText,
+  });
 
   const families = await availableEmbeddingFamilies();
   const set = await getActiveEmbeddingSet();
@@ -134,24 +136,25 @@ export async function enrichCreativeContextMedia(input: {
       });
       await recordEmbeddingMetadata({
         embeddingSetId: set.id,
-        itemId: loaded.itemId,
-        itemVersionId: loaded.itemVersionId,
+        itemId: snapshot.itemId,
+        itemVersionId: snapshot.itemVersionId,
         targetType: "media",
-        targetId: input.mediaId,
+        targetId: snapshot.mediaId,
         vectorKey: stored.vectorKey,
         dimensions: vector.length,
         checksum: fingerprint.sha256,
       });
     }
   }
-  await projectCreativeContextMedia(input.mediaId);
+  await projectCreativeContextMedia(snapshot.mediaId);
   return {
-    mediaId: input.mediaId,
-    itemId: loaded.itemId,
-    itemVersionId: loaded.itemVersionId,
+    mediaId: snapshot.mediaId,
+    itemId: snapshot.itemId,
+    itemVersionId: snapshot.itemVersionId,
+    versionAppended: snapshot.appended,
     palette,
-    caption: caption ?? null,
-    ocrText: ocrText ?? null,
+    caption: nextCaption,
+    ocrText: nextOcrText,
     contentHash: fingerprint.sha256,
     embeddingId,
     embeddingFamily: family?.id ?? null,