@agent-native/creative-context 0.1.0

package/src/client/CreativeContextSettingsLink.tsx

@@ -0,0 +1,30 @@
+import { useT } from "@agent-native/core/client";
+import { IconArrowUpRight, IconBooks } from "@tabler/icons-react";
+
+export function CreativeContextSettingsLink({
+  href = "/agent#library",
+}: {
+  href?: string;
+}) {
+  const t = useT();
+  return (
+    <a
+      id="creative-context-library"
+      href={href}
+      className="group flex scroll-mt-16 items-start gap-4 rounded-lg border border-border bg-card p-5 transition-colors hover:bg-accent/40"
+    >
+      <div className="flex size-9 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground">
+        <IconBooks className="size-4" />
+      </div>
+      <div className="min-w-0 flex-1">
+        <h2 className="text-base font-semibold">
+          {t("creativeContext.title")}
+        </h2>
+        <p className="mt-1 text-sm leading-6 text-muted-foreground">
+          {t("creativeContext.description")}
+        </p>
+      </div>
+      <IconArrowUpRight className="mt-1 size-4 text-muted-foreground transition-colors group-hover:text-foreground" />
+    </a>
+  );
+}

package/src/client/actions.ts

@@ -0,0 +1,438 @@
+import { useActionMutation, useActionQuery } from "@agent-native/core/client";
+
+import type {
+  BrandDnaPayload,
+  BrandDnaVersion,
+  BrandProfile,
+  ContextImportMode,
+  ContextJob,
+  ContextPackDetail,
+  ContextPackSummary,
+  ContextReviewItem,
+  ContextSearchResult,
+  ContextSourceStatus,
+  ContextSourceSummary,
+  CreativeContextSuggestion,
+  ImportPreviewItem,
+  UpstreamAccess,
+} from "../types.js";
+
+export const CREATIVE_CONTEXT_ACTIONS = {
+  listSources: "list-context-sources",
+  manageSource: "manage-context-source",
+  previewImport: "preview-context-import",
+  startImport: "start-context-import",
+  importStatus: "get-context-import-status",
+  listConnections: "list-context-connections",
+  recommendRoots: "recommend-context-roots",
+  search: "search-creative-context",
+  getBrandProfile: "get-brand-profile",
+  publishBrandDna: "publish-brand-dna",
+  listPacks: "list-context-packs",
+  managePack: "manage-context-pack",
+  recordFeedback: "record-context-feedback",
+  getPack: "get-context-pack",
+  reviewItems: "review-context-items",
+  listLogoCandidates: "list-canonical-logo-candidates",
+  proposeLogo: "propose-canonical-logo",
+  confirmLogo: "confirm-canonical-logo",
+  listSuggestions: "list-context-suggestions",
+  manageLayoutTemplate: "manage-layout-template",
+} as const;
+
+export interface CanonicalLogoCandidate {
+  mediaId: string;
+  itemId: string;
+  itemVersionId: string;
+  title: string;
+  mimeType: string | null;
+  thumbnailUrl: string;
+  score: number;
+}
+
+export interface ListCanonicalLogoCandidatesResult {
+  profileId: string | null;
+  candidates: CanonicalLogoCandidate[];
+}
+
+export interface ListCreativeContextSuggestionsResult {
+  suggestions: CreativeContextSuggestion[];
+  capabilities: {
+    canonicalLogo: boolean;
+    layoutTemplate: boolean;
+  };
+}
+
+export interface ListContextSourcesParams {
+  status?: ContextSourceStatus;
+  kind?: string;
+  limit?: number;
+  cursor?: string;
+}
+
+export interface ListContextSourcesResult {
+  sources: ContextSourceSummary[];
+  nextCursor?: string;
+}
+
+export interface SearchCreativeContextParams {
+  query: string;
+  sourceIds?: string[];
+  packId?: string;
+  kinds?: string[];
+  limit?: number;
+  cursor?: string;
+  snapshot?: boolean;
+  contextPackName?: string;
+}
+
+export interface SearchCreativeContextResult {
+  query: string;
+  results: ContextSearchResult[];
+  nextCursor?: string;
+  coverage: {
+    mode: "none" | "lexical" | "fts" | "vector" | "fused";
+    lanes: {
+      lexical: { available: boolean; count: number };
+      fts: { available: boolean; count: number };
+      vector: { available: boolean; count: number };
+    };
+  };
+  contextPackId: string | null;
+}
+
+export interface ListContextPacksResult {
+  packs: ContextPackSummary[];
+  nextCursor?: string;
+}
+
+export interface StartContextImportParams {
+  sourceId: string;
+  mode?: ContextImportMode;
+  itemExternalIds?: string[];
+}
+
+export interface StartContextImportResult {
+  job: ContextJob;
+}
+
+export type ManageContextSourceParams =
+  | {
+      operation: "create";
+      name: string;
+      kind: string;
+      externalRef?: string;
+      connectionId?: string;
+      config?: Record<string, unknown>;
+      upstreamAccess?: UpstreamAccess;
+    }
+  | {
+      operation: "update";
+      sourceId: string;
+      patch: {
+        name?: string;
+        externalRef?: string | null;
+        connectionId?: string | null;
+        config?: Record<string, unknown>;
+        status?: ContextSourceStatus;
+        upstreamAccess?: UpstreamAccess;
+      };
+    }
+  | {
+      operation: "archive" | "restore" | "delete";
+      sourceId: string;
+    }
+  | {
+      operation: "preview-promotion";
+      sourceId: string;
+    }
+  | {
+      operation: "promote";
+      sourceId: string;
+      confirmation: {
+        containerRef: string;
+        boundaryHash: string;
+        itemCount: number;
+      };
+    };
+
+export interface ManageContextSourceResult {
+  source: ContextSourceSummary | null;
+  deleted: boolean;
+  purgeJobId?: string;
+  promotionPreview?: {
+    sourceId: string;
+    containerRef: string;
+    boundaryHash: string;
+    itemCount: number;
+    restrictedItemCount: number;
+    targetOrgId: string;
+    callerAuthority: "org-admin" | "verified-container-owner";
+  };
+}
+
+export interface PreviewContextImportResult {
+  sourceId: string;
+  items: ImportPreviewItem[];
+  smartDefaultExternalIds: string[];
+  nextCursor?: string;
+  total?: number;
+}
+
+export interface GetContextImportStatusResult {
+  job: ContextJob | null;
+}
+
+export type CreativeContextConnectionProvider =
+  | "google_drive"
+  | "figma"
+  | "notion";
+
+export interface CreativeContextConnection {
+  connectionId: string;
+  provider: CreativeContextConnectionProvider;
+  label: string;
+}
+
+export interface ListCreativeContextConnectionsResult {
+  appId: string;
+  provider: CreativeContextConnectionProvider;
+  connections: CreativeContextConnection[];
+  autoSelectedConnectionId: string | null;
+  needsPicker: boolean;
+  needsSetup: boolean;
+  connectionsPath: string;
+  connectPath: string;
+}
+
+export type CreativeContextRecommendationProvider =
+  | "google-slides"
+  | "figma"
+  | "notion";
+
+export interface CreativeContextRootRecommendation {
+  externalId: string;
+  provider: CreativeContextRecommendationProvider;
+  kind: "page" | "presentation" | "file";
+  title: string;
+  canonicalUrl?: string;
+  sourceModifiedAt?: string;
+  containerRef?: string;
+}
+
+export interface RecommendCreativeContextRootsResult {
+  recommendations: CreativeContextRootRecommendation[];
+  persisted: false;
+  requiresExplicitBoundary: true;
+  unavailableReason?: string;
+}
+
+export interface GetBrandProfileResult {
+  profile: BrandProfile | null;
+  dna: BrandDnaVersion | null;
+}
+
+export interface PublishBrandDnaParams {
+  profileId: string;
+  proposalVersionId: string;
+  confirmation: {
+    proposalVersionId: string;
+    contentHash: string;
+  };
+}
+
+export interface PublishBrandDnaResult {
+  profile: BrandProfile;
+  dna: BrandDnaVersion;
+}
+
+export interface GetContextPackResult {
+  pack: ContextPackDetail | null;
+}
+
+export type ReviewContextItemsParams =
+  | {
+      sourceId: string;
+      operation: "list";
+      queue?: "restricted" | "all";
+      limit?: number;
+    }
+  | {
+      sourceId: string;
+      operation:
+        | "approve"
+        | "exclude"
+        | "exemplar"
+        | "normal"
+        | "ignore"
+        | "star"
+        | "unstar"
+        | "deprecate"
+        | "restore";
+      itemIds: string[];
+    };
+
+export interface ReviewContextItemsResult {
+  items: ContextReviewItem[];
+  updated: number;
+}
+
+export function useCreativeContextSources(
+  params: ListContextSourcesParams = {},
+) {
+  return useActionQuery<ListContextSourcesResult>(
+    CREATIVE_CONTEXT_ACTIONS.listSources,
+    params,
+  );
+}
+
+export function useCreativeContextSearch() {
+  return useActionMutation<
+    SearchCreativeContextResult,
+    SearchCreativeContextParams
+  >(CREATIVE_CONTEXT_ACTIONS.search);
+}
+
+export function useCreativeContextPacks() {
+  return useActionQuery<ListContextPacksResult>(
+    CREATIVE_CONTEXT_ACTIONS.listPacks,
+    { limit: 50 },
+  );
+}
+
+export function useRefreshCreativeContextSource() {
+  return useActionMutation<StartContextImportResult, StartContextImportParams>(
+    CREATIVE_CONTEXT_ACTIONS.startImport,
+  );
+}
+
+export function useManageCreativeContextSource() {
+  return useActionMutation<
+    ManageContextSourceResult,
+    ManageContextSourceParams
+  >(CREATIVE_CONTEXT_ACTIONS.manageSource);
+}
+
+export function usePreviewCreativeContextImport(sourceId: string | null) {
+  return useActionQuery<PreviewContextImportResult>(
+    CREATIVE_CONTEXT_ACTIONS.previewImport,
+    sourceId ? { sourceId, limit: 100 } : undefined,
+    { enabled: Boolean(sourceId) },
+  );
+}
+
+export function useStartCreativeContextImport() {
+  return useActionMutation<StartContextImportResult, StartContextImportParams>(
+    CREATIVE_CONTEXT_ACTIONS.startImport,
+  );
+}
+
+export function useCreativeContextImportStatus(jobId: string | null) {
+  return useActionQuery<GetContextImportStatusResult>(
+    CREATIVE_CONTEXT_ACTIONS.importStatus,
+    jobId ? { jobId } : undefined,
+    {
+      enabled: Boolean(jobId),
+      refetchInterval: (query) => {
+        const status = query.state.data?.job?.status;
+        return status === "queued" || status === "running" ? 2_000 : false;
+      },
+    },
+  );
+}
+
+export function useCreativeContextConnections(
+  provider: CreativeContextConnectionProvider | null,
+) {
+  return useActionQuery<ListCreativeContextConnectionsResult>(
+    CREATIVE_CONTEXT_ACTIONS.listConnections,
+    provider ? { provider } : undefined,
+    { enabled: Boolean(provider) },
+  );
+}
+
+export function useCreativeContextRootRecommendations(
+  provider: CreativeContextRecommendationProvider | null,
+  connectionId: string | null,
+  figmaBoundary: { figmaProjectId?: string; figmaTeamId?: string } = {},
+) {
+  return useActionQuery<RecommendCreativeContextRootsResult>(
+    CREATIVE_CONTEXT_ACTIONS.recommendRoots,
+    provider && connectionId
+      ? { provider, connectionId, limit: 15, ...figmaBoundary }
+      : undefined,
+    { enabled: Boolean(provider && connectionId) },
+  );
+}
+
+export function useCreativeContextBrandProfile() {
+  return useActionQuery<GetBrandProfileResult>(
+    CREATIVE_CONTEXT_ACTIONS.getBrandProfile,
+    {},
+  );
+}
+
+export function usePublishCreativeContextBrandDna() {
+  return useActionMutation<PublishBrandDnaResult, PublishBrandDnaParams>(
+    CREATIVE_CONTEXT_ACTIONS.publishBrandDna,
+  );
+}
+
+export function useCreativeContextPack(packId: string | null) {
+  return useActionQuery<GetContextPackResult>(
+    CREATIVE_CONTEXT_ACTIONS.getPack,
+    packId ? { packId } : undefined,
+    { enabled: Boolean(packId) },
+  );
+}
+
+export function useReviewCreativeContextItems() {
+  return useActionMutation<ReviewContextItemsResult, ReviewContextItemsParams>(
+    CREATIVE_CONTEXT_ACTIONS.reviewItems,
+  );
+}
+
+export function useCanonicalLogoCandidates(profileId?: string, enabled = true) {
+  return useActionQuery<ListCanonicalLogoCandidatesResult>(
+    CREATIVE_CONTEXT_ACTIONS.listLogoCandidates,
+    { profileId, limit: 6 },
+    { enabled },
+  );
+}
+
+export function useCreativeContextSuggestions() {
+  return useActionQuery<ListCreativeContextSuggestionsResult>(
+    CREATIVE_CONTEXT_ACTIONS.listSuggestions,
+    { limit: 50 },
+  );
+}
+
+export function useProposeCanonicalLogo() {
+  return useActionMutation<
+    CreativeContextSuggestion,
+    {
+      profileId?: string;
+      itemId: string;
+      itemVersionId?: string;
+      reason?: string;
+      payload?: Record<string, unknown>;
+    }
+  >(CREATIVE_CONTEXT_ACTIONS.proposeLogo);
+}
+
+export function useConfirmCanonicalLogo() {
+  return useActionMutation<
+    CreativeContextSuggestion,
+    { suggestionId: string; decision: "confirm" | "reject" }
+  >(CREATIVE_CONTEXT_ACTIONS.confirmLogo);
+}
+
+export function useManageLayoutTemplate() {
+  return useActionMutation<
+    CreativeContextSuggestion,
+    {
+      operation: "promote" | "demote" | "reject";
+      suggestionId: string;
+    }
+  >(CREATIVE_CONTEXT_ACTIONS.manageLayoutTemplate);
+}

package/src/client/agent-tab.tsx

@@ -0,0 +1,58 @@
+import type {
+  AgentPageScope,
+  SettingsTabItem,
+} from "@agent-native/core/client";
+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,41 @@
+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",
+      currentPackId: null,
+      pinnedPackId: null,
+    });
+  });
+
+  it("clears current and pinned packs when context is off", () => {
+    expect(
+      normalizeCreativeContextState({
+        contextMode: "off",
+        currentPackId: "current-pack",
+        pinnedPackId: "pinned-pack",
+      }),
+    ).toEqual({
+      contextMode: "off",
+      currentPackId: null,
+      pinnedPackId: null,
+    });
+  });
+
+  it("keeps valid pack ids in automatic mode", () => {
+    expect(
+      normalizeCreativeContextState({
+        contextMode: "auto",
+        currentPackId: " current-pack ",
+        pinnedPackId: "pinned-pack",
+      }),
+    ).toEqual({
+      contextMode: "auto",
+      currentPackId: "current-pack",
+      pinnedPackId: "pinned-pack",
+    });
+  });
+});

package/src/client/application-state.ts

@@ -0,0 +1,130 @@
+import {
+  getBrowserTabId,
+  readClientAppState,
+  setClientAppState,
+  useChangeVersion,
+} from "@agent-native/core/client";
+import { useCallback, useEffect, useState } from "react";
+
+export const CREATIVE_CONTEXT_STATE_KEY = "creative-context";
+
+export type CreativeContextMode = "auto" | "off";
+
+export interface CreativeContextApplicationState {
+  contextMode: CreativeContextMode;
+  currentPackId?: string | null;
+  pinnedPackId?: string | null;
+}
+
+export const DEFAULT_CREATIVE_CONTEXT_STATE: CreativeContextApplicationState = {
+  contextMode: "auto",
+  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,
+      currentPackId: null,
+      pinnedPackId: null,
+    };
+  }
+  return {
+    contextMode,
+    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", currentPackId: null, pinnedPackId: null }
+      : { ...state, contextMode: "auto" },
+  );
+}
+
+export async function setPinnedCreativeContextPack(
+  packId: string | null,
+  current?: CreativeContextApplicationState,
+): Promise<CreativeContextApplicationState> {
+  const state = current ?? (await readCreativeContextState());
+  return setCreativeContextState({
+    ...state,
+    contextMode: "auto",
+    pinnedPackId: normalizePackId(packId),
+  });
+}
+
+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 };
+}