@agent-native/creative-context 0.0.0-beta-20260820202238

package/src/client/agent-tab.tsx

@@ -0,0 +1,56 @@
+import { type AgentPageScope } from "@agent-native/core/client/agent-chat";
+import { type SettingsTabItem } from "@agent-native/core/client/settings";
+import { IconLibrary } from "@tabler/icons-react";
+import type { ReactNode } from "react";
+
+import { CreativeContextPanel } from "./CreativeContextPanel.js";
+import { creativeContextMessagesByLocale } from "./messages.js";
+
+function libraryLabel() {
+  if (typeof document === "undefined") {
+    return creativeContextMessagesByLocale["en-US"].title;
+  }
+  const locale = document.documentElement.lang;
+  return (
+    creativeContextMessagesByLocale[
+      locale as keyof typeof creativeContextMessagesByLocale
+    ] ?? creativeContextMessagesByLocale["en-US"]
+  ).title;
+}
+
+export type CreativeContextAgentTabFactory = (context: {
+  scope: AgentPageScope;
+  canManageOrg?: boolean;
+  scopeControl: ReactNode;
+}) => SettingsTabItem;
+
+export const createCreativeContextAgentTab: CreativeContextAgentTabFactory = ({
+  scope,
+  canManageOrg,
+  scopeControl,
+}) => ({
+  id: "library",
+  label: libraryLabel(),
+  icon: IconLibrary,
+  group: "creative-context",
+  keywords: "creative context library sources packs brand DNA reuse",
+  searchEntries: [
+    {
+      id: "creative-context-sources",
+      label: "Creative context sources",
+      keywords: "references imports documents assets",
+    },
+    {
+      id: "creative-context-packs",
+      label: "Context packs",
+      keywords: "generation provenance pinned",
+    },
+  ],
+  content: (
+    <CreativeContextPanel
+      scope={scope}
+      canManageOrg={canManageOrg}
+      scopeControl={scopeControl}
+    />
+  ),
+});

package/src/client/application-state.spec.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+
+import { normalizeCreativeContextState } from "./application-state.js";
+
+describe("normalizeCreativeContextState", () => {
+  it("defaults missing state to automatic context", () => {
+    expect(normalizeCreativeContextState(null)).toEqual({
+      contextMode: "auto",
+      selectedContextId: null,
+      currentPackId: null,
+      pinnedPackId: null,
+    });
+  });
+
+  it("clears current and pinned packs when context is off", () => {
+    expect(
+      normalizeCreativeContextState({
+        contextMode: "off",
+        selectedContextId: "selected-context",
+        currentPackId: "current-pack",
+        pinnedPackId: "pinned-pack",
+      }),
+    ).toEqual({
+      contextMode: "off",
+      selectedContextId: null,
+      currentPackId: null,
+      pinnedPackId: null,
+    });
+  });
+
+  it("keeps valid pack ids in automatic mode", () => {
+    expect(
+      normalizeCreativeContextState({
+        contextMode: "auto",
+        selectedContextId: " selected-context ",
+        currentPackId: " current-pack ",
+        pinnedPackId: "pinned-pack",
+      }),
+    ).toEqual({
+      contextMode: "auto",
+      selectedContextId: "selected-context",
+      currentPackId: "current-pack",
+      pinnedPackId: "pinned-pack",
+    });
+  });
+});

package/src/client/application-state.ts

@@ -0,0 +1,158 @@
+import {
+  getBrowserTabId,
+  readClientAppState,
+  setClientAppState,
+  useChangeVersion,
+} from "@agent-native/core/client/hooks";
+import { useCallback, useEffect, useState } from "react";
+
+export const CREATIVE_CONTEXT_STATE_KEY = "creative-context";
+
+export type CreativeContextMode = "auto" | "off";
+
+export interface CreativeContextApplicationState {
+  contextMode: CreativeContextMode;
+  selectedContextId?: string | null;
+  currentPackId?: string | null;
+  pinnedPackId?: string | null;
+}
+
+export const DEFAULT_CREATIVE_CONTEXT_STATE: CreativeContextApplicationState = {
+  contextMode: "auto",
+  selectedContextId: null,
+  currentPackId: null,
+  pinnedPackId: null,
+};
+
+function normalizePackId(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+export function normalizeCreativeContextState(
+  value: unknown,
+): CreativeContextApplicationState {
+  if (!value || typeof value !== "object") {
+    return { ...DEFAULT_CREATIVE_CONTEXT_STATE };
+  }
+  const record = value as Record<string, unknown>;
+  const contextMode: CreativeContextMode =
+    record.contextMode === "off" ? "off" : "auto";
+  if (contextMode === "off") {
+    return {
+      contextMode,
+      selectedContextId: null,
+      currentPackId: null,
+      pinnedPackId: null,
+    };
+  }
+  return {
+    contextMode,
+    selectedContextId: normalizePackId(record.selectedContextId),
+    currentPackId: normalizePackId(record.currentPackId),
+    pinnedPackId: normalizePackId(record.pinnedPackId),
+  };
+}
+
+export async function readCreativeContextState(options?: {
+  signal?: AbortSignal;
+}): Promise<CreativeContextApplicationState> {
+  const value = await readClientAppState<CreativeContextApplicationState>(
+    CREATIVE_CONTEXT_STATE_KEY,
+    options,
+  );
+  return normalizeCreativeContextState(value);
+}
+
+export async function setCreativeContextState(
+  value: CreativeContextApplicationState,
+): Promise<CreativeContextApplicationState> {
+  const normalized = normalizeCreativeContextState(value);
+  await setClientAppState(CREATIVE_CONTEXT_STATE_KEY, normalized, {
+    requestSource: getBrowserTabId(),
+  });
+  return normalized;
+}
+
+export async function setCreativeContextMode(
+  mode: CreativeContextMode,
+  current?: CreativeContextApplicationState,
+): Promise<CreativeContextApplicationState> {
+  const state = current ?? (await readCreativeContextState());
+  return setCreativeContextState(
+    mode === "off"
+      ? {
+          contextMode: "off",
+          selectedContextId: null,
+          currentPackId: null,
+          pinnedPackId: null,
+        }
+      : {
+          ...state,
+          contextMode: "auto",
+          selectedContextId: null,
+          pinnedPackId: null,
+        },
+  );
+}
+
+export async function setPinnedCreativeContextPack(
+  packId: string | null,
+  current?: CreativeContextApplicationState,
+): Promise<CreativeContextApplicationState> {
+  const state = current ?? (await readCreativeContextState());
+  return setCreativeContextState({
+    ...state,
+    contextMode: "auto",
+    selectedContextId: null,
+    pinnedPackId: normalizePackId(packId),
+  });
+}
+
+export async function setSelectedCreativeContext(
+  contextId: string | null,
+  current?: CreativeContextApplicationState,
+): Promise<CreativeContextApplicationState> {
+  const state = current ?? (await readCreativeContextState());
+  return setCreativeContextState({
+    ...state,
+    contextMode: "auto",
+    selectedContextId: normalizePackId(contextId),
+    pinnedPackId: null,
+  });
+}
+
+export function useCreativeContextState() {
+  const appStateVersion = useChangeVersion("app-state");
+  const [state, setState] = useState<CreativeContextApplicationState>(
+    DEFAULT_CREATIVE_CONTEXT_STATE,
+  );
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    setIsLoading(true);
+    readCreativeContextState({ signal: controller.signal })
+      .then((next) => {
+        setState(next);
+        setError(null);
+      })
+      .catch((cause: unknown) => {
+        if (controller.signal.aborted) return;
+        setError(cause instanceof Error ? cause : new Error(String(cause)));
+      })
+      .finally(() => {
+        if (!controller.signal.aborted) setIsLoading(false);
+      });
+    return () => controller.abort();
+  }, [appStateVersion]);
+
+  const save = useCallback(async (next: CreativeContextApplicationState) => {
+    const saved = await setCreativeContextState(next);
+    setState(saved);
+    setError(null);
+    return saved;
+  }, []);
+
+  return { state, setState: save, isLoading, error };
+}

package/src/client/google-slides-picker.spec.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+
+import { googleSlidesPickerSelections } from "./google-slides-picker.js";
+
+describe("googleSlidesPickerSelections", () => {
+  it("returns unique presentation ids with safe canonical URLs", () => {
+    expect(
+      googleSlidesPickerSelections({
+        docs: [
+          {
+            id: "deck_123456789",
+            name: "Launch",
+            url: "https://attacker.example/x",
+          },
+          { id: "deck_123456789", name: "Duplicate" },
+          { id: "deck_987654321", name: "Roadmap" },
+          { id: "bad/id", name: "Invalid id" },
+          { name: "Missing id" },
+        ],
+      }),
+    ).toEqual([
+      {
+        externalId: "deck_123456789",
+        title: "Launch",
+        canonicalUrl:
+          "https://docs.google.com/presentation/d/deck_123456789/edit",
+      },
+      {
+        externalId: "deck_987654321",
+        title: "Roadmap",
+        canonicalUrl:
+          "https://docs.google.com/presentation/d/deck_987654321/edit",
+      },
+    ]);
+  });
+});

package/src/client/google-slides-picker.ts

@@ -0,0 +1,146 @@
+const GOOGLE_PICKER_SCRIPT = "https://apis.google.com/js/api.js";
+const GOOGLE_SLIDES_MIME_TYPE = "application/vnd.google-apps.presentation";
+const GOOGLE_PICKER_LOAD_TIMEOUT_MS = 15_000;
+const GOOGLE_PICKER_SELECTION_TIMEOUT_MS = 5 * 60_000;
+const GOOGLE_DRIVE_FILE_ID = /^[A-Za-z0-9_-]{8,256}$/;
+
+declare global {
+  interface Window {
+    gapi?: any;
+    google?: any;
+    __creativeContextGooglePickerScript?: Promise<void>;
+  }
+}
+
+export interface GoogleSlidesPickerSelection {
+  externalId: string;
+  title: string;
+  canonicalUrl?: string;
+}
+
+export function googleSlidesPickerSelections(
+  value: unknown,
+): GoogleSlidesPickerSelection[] {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+  const docs = (value as { docs?: unknown }).docs;
+  if (!Array.isArray(docs)) return [];
+  const seen = new Set<string>();
+  return docs.flatMap((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) return [];
+    const record = entry as Record<string, unknown>;
+    const externalId = typeof record.id === "string" ? record.id.trim() : "";
+    if (!GOOGLE_DRIVE_FILE_ID.test(externalId) || seen.has(externalId)) {
+      return [];
+    }
+    seen.add(externalId);
+    const title =
+      typeof record.name === "string" && record.name.trim()
+        ? record.name.trim().slice(0, 300)
+        : "Google Slides presentation";
+    const canonicalUrl = `https://docs.google.com/presentation/d/${encodeURIComponent(externalId)}/edit`;
+    return [{ externalId, title, canonicalUrl }];
+  });
+}
+
+async function withGooglePickerTimeout<T>(
+  promise: Promise<T>,
+  message: string,
+  timeoutMs = GOOGLE_PICKER_LOAD_TIMEOUT_MS,
+): Promise<T> {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<never>((_, reject) => {
+        timeout = setTimeout(() => reject(new Error(message)), timeoutMs);
+      }),
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+async function loadGooglePicker(): Promise<void> {
+  if (!window.gapi) {
+    window.__creativeContextGooglePickerScript ??= new Promise(
+      (resolve, reject) => {
+        const script = document.createElement("script");
+        script.src = GOOGLE_PICKER_SCRIPT;
+        script.async = true;
+        script.onload = () => resolve();
+        script.onerror = () =>
+          reject(new Error("Could not load Google Picker."));
+        document.head.appendChild(script);
+      },
+    );
+    await withGooglePickerTimeout(
+      window.__creativeContextGooglePickerScript,
+      "Google Picker script timed out.",
+    );
+  }
+  if (!window.gapi?.load) throw new Error("Google Picker did not initialize.");
+  await withGooglePickerTimeout(
+    new Promise<void>((resolve, reject) => {
+      window.gapi.load("picker", {
+        callback: resolve,
+        onerror: () => reject(new Error("Could not load Google Picker.")),
+      });
+    }),
+    "Google Picker initialization timed out.",
+  );
+}
+
+export async function chooseGoogleSlidesPresentations(input: {
+  accessToken: string;
+  apiKey: string;
+  appId: string;
+}): Promise<GoogleSlidesPickerSelection[]> {
+  await loadGooglePicker();
+  const google = window.google;
+  if (!google?.picker) throw new Error("Google Picker is unavailable.");
+  return withGooglePickerTimeout(
+    new Promise((resolve, reject) => {
+      const view = new google.picker.DocsView(
+        google.picker.ViewId.PRESENTATIONS,
+      )
+        .setMimeTypes(GOOGLE_SLIDES_MIME_TYPE)
+        .setSelectFolderEnabled(false);
+      const picker = new google.picker.PickerBuilder()
+        .addView(view)
+        .enableFeature(google.picker.Feature.MULTISELECT_ENABLED)
+        .setOAuthToken(input.accessToken)
+        .setDeveloperKey(input.apiKey)
+        .setAppId(input.appId)
+        .setTitle("Choose Google Slides presentations")
+        .setCallback((data: unknown) => {
+          if (
+            data &&
+            typeof data === "object" &&
+            (data as { action?: unknown }).action ===
+              google.picker.Action.CANCEL
+          ) {
+            resolve([]);
+            return;
+          }
+          if (
+            !data ||
+            typeof data !== "object" ||
+            (data as { action?: unknown }).action !==
+              google.picker.Action.PICKED
+          ) {
+            return;
+          }
+          const selections = googleSlidesPickerSelections(data);
+          if (!selections.length) {
+            reject(new Error("Google Picker returned no presentations."));
+            return;
+          }
+          resolve(selections);
+        })
+        .build();
+      picker.setVisible(true);
+    }),
+    "Google Picker selection timed out.",
+    GOOGLE_PICKER_SELECTION_TIMEOUT_MS,
+  );
+}

package/src/client/index.ts

@@ -0,0 +1,102 @@
+export {
+  CREATIVE_CONTEXT_ACTIONS,
+  parseContextMemberships,
+  parseContextMembershipsForResource,
+  parseCreativeContexts,
+  useContextMemberships,
+  useCreativeContextBrandProfile,
+  useCreativeContexts,
+  useCreativeContextGooglePickerSession,
+  useCreativeContextImportStatus,
+  useCreativeContextPack,
+  useCreativeContextPacks,
+  useCreativeContextSearch,
+  useCreativeContextSources,
+  useManageCreativeContextSource,
+  useManageCreativeContext,
+  useManageContextMembership,
+  usePreviewCreativeContextImport,
+  usePublishCreativeContextBrandDna,
+  useRefreshCreativeContextSource,
+  useReviewCreativeContextItems,
+  useStartCreativeContextImport,
+  type GetBrandProfileResult,
+  type CreativeContextMembership,
+  type CreativeContextMembershipRank,
+  type CreativeContextPolicy,
+  type CreativeContextSummary,
+  type GetContextImportStatusResult,
+  type GetContextPackResult,
+  type GetGooglePickerSessionResult,
+  type ListContextPacksResult,
+  type ListContextMembershipsParams,
+  type ListContextMembershipsResult,
+  type ListCreativeContextsParams,
+  type ListCreativeContextsResult,
+  type ManageContextMembershipParams,
+  type ManageContextMembershipResult,
+  type ManageCreativeContextParams,
+  type ManageCreativeContextResult,
+  type ListContextSourcesParams,
+  type ListContextSourcesResult,
+  type ManageContextSourceParams,
+  type ManageContextSourceResult,
+  type PreviewContextImportResult,
+  type PublishBrandDnaParams,
+  type PublishBrandDnaResult,
+  type ReviewContextItemsParams,
+  type ReviewContextItemsResult,
+  type SearchCreativeContextParams,
+  type SearchCreativeContextResult,
+  type StartContextImportParams,
+  type StartContextImportResult,
+} from "./actions.js";
+export {
+  CREATIVE_CONTEXT_STATE_KEY,
+  DEFAULT_CREATIVE_CONTEXT_STATE,
+  normalizeCreativeContextState,
+  readCreativeContextState,
+  setCreativeContextMode,
+  setSelectedCreativeContext,
+  setCreativeContextState,
+  setPinnedCreativeContextPack,
+  useCreativeContextState,
+  type CreativeContextApplicationState,
+  type CreativeContextMode,
+} from "./application-state.js";
+export {
+  CreativeContextChip,
+  CreativeContextComposerChip,
+  resolveCreativeContextChipSelection,
+  type CreativeContextChipProps,
+  type CreativeContextChipSelection,
+} from "./CreativeContextChip.js";
+export {
+  CreativeContextPanel,
+  type CreativeContextPanelProps,
+} from "./CreativeContextPanel.js";
+export {
+  CreativeContextShareSheet,
+  CreativeContextShareTab,
+  creativeContextSafePreviewUrl,
+  normalizeCreativeContextResources,
+  requiresBroaderPublication,
+  submitCreativeContextResources,
+  type CreativeContextResourceDescriptor,
+  type CreativeContextResourcePreview,
+  type CreativeContextShareTabProps,
+} from "./CreativeContextShareTab.js";
+export { CreativeContextSettingsLink } from "./CreativeContextSettingsLink.js";
+export {
+  createCreativeContextAgentTab,
+  type CreativeContextAgentTabFactory,
+} from "./agent-tab.js";
+export {
+  creativeContextMessagesByLocale,
+  type CreativeContextMessages,
+} from "./messages.js";
+export {
+  delimitUntrustedReference,
+  sanitizeUntrustedReference,
+  UNTRUSTED_REFERENCE_ROLE,
+} from "../untrusted-reference.js";