@agent-native/core 0.103.1 → 0.105.0

package/corpus/templates/design/actions/generate-design.ts

@@ -11,6 +11,19 @@ import {
 } from "@agent-native/core/collab";
 import { buildDeepLink } from "@agent-native/core/server";
 import { assertAccess } from "@agent-native/core/sharing";
+import {
+  getGenerationCreativeContext,
+  mergeCreativeContextReuseLabels,
+  recordGenerationCreativeContext,
+  replaceCreativeContextElementProvenance,
+  resolveGenerationCreativeContext,
+  validateCreativeContextReuseLabels,
+  validateGenerationCreativeContext,
+} from "@agent-native/creative-context/server";
+import type {
+  CreativeContextElementProvenance,
+  CreativeContextReuseLabel,
+} from "@agent-native/creative-context/types";
 import { eq } from "drizzle-orm";
 import { nanoid } from "nanoid";
 import { z } from "zod";
@@ -74,6 +87,34 @@ const DEFAULT_RESPONSIVE_BREAKPOINTS = [390, 768, 1440].map((widthPx) => ({
   prefix: widthToPrefix(widthPx),
 }));
 
+const reuseLabelSchema = z
+  .object({
+    itemId: z.string().min(1).optional(),
+    itemVersionId: z.string().min(1).optional(),
+    kind: z.string().min(1),
+    label: z.string().min(1),
+    dataRole: z.literal("untrusted-reference").default("untrusted-reference"),
+    elementId: z.string().min(1).optional(),
+    influence: z
+      .enum(["reused", "adapted", "reference-conditioned", "generated"])
+      .optional(),
+  })
+  .superRefine((label, context) => {
+    const influence = label.influence ?? "reference-conditioned";
+    if (Boolean(label.itemId) !== Boolean(label.itemVersionId)) {
+      context.addIssue({
+        code: "custom",
+        message: "itemId and itemVersionId must be provided together",
+      });
+    }
+    if (influence !== "generated" && !label.itemId) {
+      context.addIssue({
+        code: "custom",
+        message: "Only generated labels may omit context item ids",
+      });
+    }
+  });
+
 function hasBreakpointSet(value: unknown): boolean {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return false;
@@ -128,26 +169,190 @@ function withGenerationSessionLock<T>(
   return next;
 }
 
-async function updateGenerationSessionForSavedFiles(
+interface DesignCreativeContextProvenance {
+  contextMode: "off" | "auto" | "pinned";
+  contextPackId: string | null;
+  reuseLabels: CreativeContextReuseLabel[];
+}
+
+async function resolveDesignCreativeContext(input: {
+  prompt: string;
+  generationSession: DesignGenerationSession | null;
+  contextPackId?: string;
+  contextModeOverride?: "off";
+  reuseLabels: CreativeContextReuseLabel[];
+}): Promise<DesignCreativeContextProvenance> {
+  if (input.contextModeOverride === "off") {
+    const validated = await validateGenerationCreativeContext({
+      contextPackId: input.contextPackId,
+      contextModeOverride: "off",
+      reuseLabels: input.reuseLabels,
+    });
+    return {
+      contextMode: validated.contextMode,
+      contextPackId: validated.contextPackId,
+      reuseLabels: validated.reuseLabels,
+    };
+  }
+
+  const sessionContext = input.generationSession?.creativeContext;
+  if (sessionContext) {
+    if (
+      input.contextPackId !== undefined &&
+      input.contextPackId !== sessionContext.contextPackId
+    ) {
+      throw new Error(
+        "generate-design must preserve the generation session's creative-context pack",
+      );
+    }
+    const requestedLabels = input.reuseLabels.length
+      ? input.reuseLabels
+      : sessionContext.reuseLabels;
+    if (!sessionContext.contextPackId) {
+      return {
+        contextMode: sessionContext.contextMode,
+        contextPackId: null,
+        reuseLabels: validateCreativeContextReuseLabels(requestedLabels, {
+          generatedOnly: true,
+        }),
+      };
+    }
+    const validated = await validateGenerationCreativeContext({
+      contextPackId: sessionContext.contextPackId,
+      contextPackSource: "inherited",
+      reuseLabels: requestedLabels,
+      reuseLabelsSource: input.reuseLabels.length ? "explicit" : "inherited",
+    });
+    return {
+      contextMode: sessionContext.contextMode,
+      contextPackId: validated.contextPackId,
+      reuseLabels: validated.reuseLabels,
+    };
+  }
+
+  if (input.contextPackId) {
+    const validated = await validateGenerationCreativeContext({
+      contextPackId: input.contextPackId,
+      reuseLabels: input.reuseLabels.length ? input.reuseLabels : undefined,
+    });
+    return {
+      contextMode: validated.contextMode,
+      contextPackId: validated.contextPackId,
+      reuseLabels: validated.reuseLabels,
+    };
+  }
+
+  const resolved = await resolveGenerationCreativeContext({
+    query: input.prompt,
+    role: "design",
+  });
+  if (!input.reuseLabels.length) {
+    return {
+      contextMode: resolved.contextMode,
+      contextPackId: resolved.contextPackId,
+      reuseLabels: resolved.reuseLabels,
+    };
+  }
+  const validated = await validateGenerationCreativeContext({
+    contextPackId: resolved.contextPackId,
+    reuseLabels: input.reuseLabels,
+  });
+  return {
+    contextMode: validated.contextMode,
+    contextPackId: validated.contextPackId,
+    reuseLabels: validated.reuseLabels,
+  };
+}
+
+function provenanceForSavedFiles(
+  savedFiles: readonly { id: string; filename: string }[],
+  generationSession: DesignGenerationSession | null,
+  reuseLabels: readonly CreativeContextReuseLabel[],
+): CreativeContextElementProvenance[] {
+  return savedFiles.flatMap((file) => {
+    const frame = generationSession?.frames.find(
+      (candidate) => candidate.filename === file.filename,
+    );
+    const elementId = frame?.frameId ?? file.id;
+    const labels = reuseLabels.filter(
+      (label) =>
+        !label.elementId ||
+        label.elementId === file.id ||
+        label.elementId === file.filename ||
+        label.elementId === frame?.frameId,
+    );
+    if (!labels.length) {
+      return [
+        {
+          elementId,
+          influence: "generated" as const,
+          label: file.filename,
+        },
+      ];
+    }
+    return labels.map((label) => ({
+      elementId,
+      influence: label.influence ?? ("reference-conditioned" as const),
+      ...(label.itemId ? { itemId: label.itemId } : {}),
+      ...(label.itemVersionId ? { itemVersionId: label.itemVersionId } : {}),
+      label: label.label,
+    }));
+  });
+}
+
+async function finalizeGenerationForSavedFiles(
   designId: string,
-  savedFilenames: string[],
+  savedFiles: readonly { id: string; filename: string }[],
+  generationSession: DesignGenerationSession | null,
+  creativeContext: DesignCreativeContextProvenance,
 ) {
   await withGenerationSessionLock(designId, async () => {
     const key = designGenerationSessionKey(designId);
     const rawSession = await readAppState(key).catch(() => null);
-    if (!rawSession || typeof rawSession !== "object") return;
-    const session = rawSession as unknown as DesignGenerationSession;
-    if (session.designId !== designId || !Array.isArray(session.frames)) {
-      return;
+    if (rawSession && typeof rawSession === "object") {
+      const session = rawSession as unknown as DesignGenerationSession;
+      if (session.designId === designId && Array.isArray(session.frames)) {
+        const nextSession = updateGenerationSessionWithSavedFiles(
+          session,
+          savedFiles.map((file) => file.filename),
+        );
+        if (nextSession !== session) {
+          await writeAppState(
+            key,
+            nextSession as unknown as Record<string, unknown>,
+          );
+        }
+      }
     }
 
-    const nextSession = updateGenerationSessionWithSavedFiles(
-      session,
-      savedFilenames,
+    const nextElementProvenance = provenanceForSavedFiles(
+      savedFiles,
+      generationSession,
+      creativeContext.reuseLabels,
     );
-    if (nextSession === session) return;
-
-    await writeAppState(key, nextSession as unknown as Record<string, unknown>);
+    const previous =
+      creativeContext.contextMode === "off"
+        ? null
+        : await getGenerationCreativeContext({
+            appId: "design",
+            artifactType: "design",
+            artifactId: designId,
+          });
+    const elementProvenance =
+      previous?.contextMode === creativeContext.contextMode &&
+      previous.contextPackId === creativeContext.contextPackId
+        ? replaceCreativeContextElementProvenance(
+            previous.elementProvenance,
+            nextElementProvenance,
+          )
+        : nextElementProvenance;
+    await recordGenerationCreativeContext({
+      appId: "design",
+      artifactType: "design",
+      artifactId: designId,
+      ...creativeContext,
+      elementProvenance,
+    });
   });
 }
 
@@ -190,6 +395,22 @@ const generateDesignAgentParameters = {
         "Optional JSON array of overview-canvas placements keyed by filename or fileId. " +
         "Pass explicit x/y/width/height for every generated screen; desktop is 1440x1024.",
     },
+    contextPackId: {
+      type: "string",
+      description:
+        "Immutable creative-context pack. Omit to preserve the active generation session pack.",
+    },
+    contextModeOverride: {
+      type: "string",
+      enum: ["off"],
+      description:
+        "Disable Creative Context for this generation only without changing the saved preference.",
+    },
+    reuseLabels: {
+      type: "string",
+      description:
+        "Optional JSON array of exact item/version labels, with elementId set to a target filename or frame id when evidence applies to one screen.",
+    },
     primaryViewport: {
       type: "string",
       enum: ["mobile", "tablet", "desktop"],
@@ -353,6 +574,26 @@ const generateDesignAction = defineAction({
           "Reference each screen by filename or fileId and include x/y/width/height " +
           "from generate-screens regions or your planned canvas layout.",
       ),
+    contextPackId: z
+      .string()
+      .optional()
+      .describe(
+        "Immutable creative-context pack. Omit to preserve the generation session pack.",
+      ),
+    contextModeOverride: z
+      .literal("off")
+      .optional()
+      .describe(
+        "Disable Creative Context for this generation only without changing the saved preference.",
+      ),
+    reuseLabels: z
+      .preprocess(
+        (value) => (typeof value === "string" ? JSON.parse(value) : value),
+        z.array(reuseLabelSchema).optional().default([]),
+      )
+      .describe(
+        "Exact item/version labels used by the generated files or frames.",
+      ),
     primaryViewport: z
       .enum(["mobile", "tablet", "desktop"])
       .optional()
@@ -381,11 +622,26 @@ const generateDesignAction = defineAction({
     tweaks,
     canvasFrames,
     primaryViewport,
+    contextPackId,
+    contextModeOverride,
+    reuseLabels,
   }) => {
     await assertAccess("design", designId, "editor");
     if (designSystemId) {
       await assertAccess("design-system", designSystemId, "viewer");
     }
+    const rawGenerationSession = (await readAppState(
+      designGenerationSessionKey(designId),
+    ).catch(() => null)) as DesignGenerationSession | null;
+    const generationSession =
+      rawGenerationSession?.designId === designId ? rawGenerationSession : null;
+    const creativeContextProvenance = await resolveDesignCreativeContext({
+      prompt,
+      generationSession,
+      contextPackId,
+      contextModeOverride,
+      reuseLabels,
+    });
 
     const db = getDb();
     const now = new Date().toISOString();
@@ -579,6 +835,7 @@ const generateDesignAction = defineAction({
           lastPrompt: prompt,
           generatedAt: now,
           fileCount: files.length,
+          creativeContext: creativeContextProvenance,
         };
         if (normalizedTweaks !== undefined) {
           mergedData.tweaks = normalizedTweaks;
@@ -659,6 +916,10 @@ const generateDesignAction = defineAction({
           current.lastPrompt !== prompt ||
           current.generatedAt !== now ||
           current.fileCount !== files.length ||
+          !jsonValuesEqual(
+            current.creativeContext,
+            creativeContextProvenance,
+          ) ||
           (normalizedTweaks !== undefined &&
             !jsonValuesEqual(current.tweaks, normalizedTweaks))
         ) {
@@ -700,9 +961,11 @@ const generateDesignAction = defineAction({
         .where(eq(schema.designs.id, designId));
     }
 
-    await updateGenerationSessionForSavedFiles(
+    await finalizeGenerationForSavedFiles(
       designId,
-      savedFiles.map((file) => file.filename),
+      savedFiles,
+      generationSession,
+      creativeContextProvenance,
     );
 
     return {
@@ -712,6 +975,7 @@ const generateDesignAction = defineAction({
       savedFiles,
       placedFrames,
       fileCount: savedFiles.length,
+      ...creativeContextProvenance,
     };
   },
   link: ({ result }) => {

package/corpus/templates/design/actions/generate-screens.ts

@@ -2,6 +2,10 @@ import { defineAction, embedApp } from "@agent-native/core";
 import { writeAppState } from "@agent-native/core/application-state";
 import { buildDeepLink } from "@agent-native/core/server";
 import { assertAccess } from "@agent-native/core/sharing";
+import {
+  recordGenerationCreativeContext,
+  resolveGenerationCreativeContext,
+} from "@agent-native/creative-context/server";
 import { eq } from "drizzle-orm";
 import { nanoid } from "nanoid";
 import { z } from "zod";
@@ -257,6 +261,12 @@ export default defineAction({
       .optional()
       .default([])
       .describe("Selected frame/image/reference ids attached as context"),
+    contextModeOverride: z
+      .literal("off")
+      .optional()
+      .describe(
+        "Disable Creative Context for this generation session only without changing the saved preference.",
+      ),
   }),
   mcpApp: {
     compactCatalog: true,
@@ -268,11 +278,28 @@ export default defineAction({
       height: 720,
     }),
   },
-  run: async ({ designId, prompt, screens, designSystemId, contextRefs }) => {
+  run: async ({
+    designId,
+    prompt,
+    screens,
+    designSystemId,
+    contextRefs,
+    contextModeOverride,
+  }) => {
     await assertAccess("design", designId, "editor");
     if (designSystemId) {
       await assertAccess("design-system", designSystemId, "viewer");
     }
+    const creativeContext = await resolveGenerationCreativeContext({
+      query: prompt,
+      role: "design",
+      contextModeOverride,
+    });
+    const creativeContextProvenance = {
+      contextMode: creativeContext.contextMode,
+      contextPackId: creativeContext.contextPackId,
+      reuseLabels: creativeContext.reuseLabels,
+    };
 
     const regionSizes = screens.map(regionSizeForScreen);
     const regions = assignRegionsForSizes(regionSizes, {
@@ -357,6 +384,7 @@ export default defineAction({
       designSystemId,
       prompt,
       contextRefs,
+      creativeContext: creativeContextProvenance,
       frames,
       startedAt: new Date().toISOString(),
     };
@@ -371,6 +399,17 @@ export default defineAction({
       editorView: "overview",
       path: `/design/${encodeURIComponent(designId)}?view=overview`,
     });
+    await recordGenerationCreativeContext(
+      {
+        appId: "design",
+        artifactType: "generation-session",
+        artifactId: session.id,
+        ...creativeContextProvenance,
+      },
+      {
+        artifactAccess: { resourceType: "design", resourceId: designId },
+      },
+    );
 
     const targets = frames.map((frame, index) => {
       const requested = screens[index]!;
@@ -398,6 +437,8 @@ export default defineAction({
       status: session.status,
       frames,
       targets,
+      ...creativeContextProvenance,
+      contextResults: creativeContext.results,
       path: `/design/${encodeURIComponent(designId)}?view=overview`,
       embed: true,
       nextRequiredAction:

package/corpus/templates/design/agent-native.app-skill.json

@@ -56,6 +56,10 @@
       "path": ".agents/skills/design-review-feedback",
       "visibility": "both",
       "exportAs": "design-review-feedback"
+    },
+    {
+      "path": ".agents/skills/creative-context",
+      "visibility": "internal"
     }
   ],
   "hostAdapters": [

package/corpus/templates/design/app/components/layout/Layout.tsx

@@ -6,6 +6,7 @@ import {
   useSession,
   useT,
 } from "@agent-native/core/client";
+import { CreativeContextComposerChip } from "@agent-native/creative-context/client";
 import { HeaderActionsProvider } from "@agent-native/toolkit/app-shell";
 import { IconMenu2 } from "@tabler/icons-react";
 import {
@@ -163,9 +164,12 @@ export function Layout({ children }: LayoutProps) {
           threadFooterSlot={designQuestionsWaitingSlot}
           onComposerTextChange={handleComposerTextChange}
           composerSlot={
-            detectedFigmaComposerLink ? (
-              <FigmaLinkComposerBubble link={detectedFigmaComposerLink} />
-            ) : null
+            <>
+              <CreativeContextComposerChip />
+              {detectedFigmaComposerLink ? (
+                <FigmaLinkComposerBubble link={detectedFigmaComposerLink} />
+              ) : null}
+            </>
           }
         >
           <div className="agent-layout-shell flex h-dvh w-full overflow-hidden bg-background text-foreground">

package/corpus/templates/design/app/i18n/zh-TW.ts

@@ -1,3 +1,5 @@
+import { creativeContextMessagesByLocale } from "@agent-native/creative-context/messages";
+
 import {
   attachLocalizedKeyboardShortcuts,
   keyboardKeyLabels,
@@ -6,6 +8,7 @@ import {
 import { designTemplateFeatureOverrides } from "../i18n-template-feature";
 
 const messages = {
+  creativeContext: creativeContextMessagesByLocale["zh-TW"],
   root: {
     commandActions: "操作",
     commandSearch: "搜尋",

package/corpus/templates/design/app/i18n-data.ts

@@ -1,4 +1,5 @@
 import type { LocaleCode } from "@agent-native/core/client";
+import { creativeContextMessagesByLocale } from "@agent-native/creative-context/messages";
 
 import { breakpointBarOverrides } from "./i18n-breakpoints";
 import {
@@ -11,6 +12,7 @@ import { designTemplateFeatureOverrides } from "./i18n-template-feature";
 import zhTW from "./i18n/zh-TW";
 
 const enUS = {
+  creativeContext: creativeContextMessagesByLocale["en-US"],
   root: {
     commandActions: "Actions",
     commandSearch: "Search",
@@ -31,10 +33,10 @@ const enUS = {
     collapseSidebar: "Collapse sidebar",
   },
   settings: {
-    agentTitle: "Agent settings",
+    agentTitle: "Agent workspace",
     agentDescription:
-      "Open the agent sidebar settings for model, API keys, automations, voice, and other agent controls.",
-    openAgentSettings: "Open agent settings",
+      "Open the agent workspace for model, API keys, automations, voice, and other agent controls.",
+    openAgentSettings: "Open agent workspace",
     languageTitle: "Language",
     languageDescription: "Choose the interface language for Design.",
     languageLabel: "Interface language",
@@ -1571,7 +1573,11 @@ function mergeLocalizedMessages(
   overrides: PartialMessages,
 ): Messages {
   return attachLocalizedKeyboardShortcuts(
-    mergeMessages(overrides),
+    mergeMessages(
+      mergePartialMessages(overrides, {
+        creativeContext: creativeContextMessagesByLocale[locale],
+      }),
+    ),
     keyboardShortcutLabels[locale],
     keyboardKeyLabels[locale],
   );

package/corpus/templates/design/app/routes/agent.tsx

@@ -1,4 +1,5 @@
 import { AgentTabsPage, useT } from "@agent-native/core/client";
+import { createCreativeContextAgentTab } from "@agent-native/creative-context/client";
 import { useSetPageTitle } from "@agent-native/toolkit/app-shell";
 
 import messages from "@/i18n/en-US";
@@ -11,5 +12,5 @@ export default function AgentRoute() {
   const t = useT();
   useSetPageTitle(t("settings.agentTitle"));
 
-  return <AgentTabsPage />;
+  return <AgentTabsPage extraTabFactories={[createCreativeContextAgentTab]} />;
 }

package/corpus/templates/design/app/routes/settings.tsx

@@ -7,6 +7,7 @@ import {
   type SettingsSearchEntry,
 } from "@agent-native/core/client";
 import { TeamPage } from "@agent-native/core/client/org";
+import { CreativeContextSettingsLink } from "@agent-native/creative-context/client";
 import { useMemo } from "react";
 
 import {
@@ -48,6 +49,8 @@ export default function SettingsRoute() {
         generalSearchEntries={generalSearchEntries}
         general={
           <div className="mx-auto w-full max-w-2xl space-y-6">
+            <CreativeContextSettingsLink />
+
             <Card id="language" className="scroll-mt-16">
               <CardHeader>
                 <CardTitle className="text-base">

package/corpus/templates/design/changelog/2026-07-16-creative-context-library.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-16
+---
+
+The Agent workspace now includes a Library for reusing verified creative context, including version-pinned Figma designs cloned as editable HTML/CSS without regeneration.

package/corpus/templates/design/changelog/2026-07-16-design-agent-chat-no-longer-shows-a-separate-workspace-header.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-16
+---
+
+Design agent chat now stays inline with the editor rail without a separate Chat or Workspace header.

package/corpus/templates/design/package.json

@@ -19,6 +19,7 @@
   },
   "dependencies": {
     "@agent-native/core": "workspace:*",
+    "@agent-native/creative-context": "workspace:*",
     "@agent-native/pinpoint": "workspace:*",
     "@agent-native/toolkit": "workspace:*",
     "@fontsource-variable/inter": "^5.2.8",