@agent-native/core 0.103.1 → 0.105.0

package/corpus/templates/design/AGENTS.md

@@ -167,6 +167,10 @@ patterns live in `.agents/skills/`.
   `inspectorTab: "extensions"` after installing it.
 - Follow linked design-system tokens and `customInstructions` whenever present;
   explicit user instructions in the current turn still win.
+- Before generation, follow the creative-context reuse ladder in
+  `.agents/skills/creative-context/SKILL.md`: explicit request and current
+  design first, then a pinned/current pack, then narrow library search. Respect
+  `creative-context.contextMode: "off"` without silently restoring a pack.
 - For reusable design-system setup from Figma, connected code/GitHub, local
   code/design files, or optional `design.md`, use Builder-backed DSI indexing
   through `index-design-system-with-builder` or the Design System Setup `.fig`
@@ -473,6 +477,8 @@ Read the relevant skill before deeper work:
 - `responsive-breakpoints` for Framer-style breakpoint editing (single DOM,
   cascading width-scoped overrides, the managed breakpoints media block).
 - `design-systems` for tokens, brand extraction, and linked systems.
+- `creative-context` for cross-app source reuse, pinned packs, provenance, and
+  context opt-out.
 - `export-handoff` for HTML/PNG/SVG/ZIP/code handoff.
 - `full-app-build` for flag-gated fusion-backed full app building.
 - `shader-fills` for code-backed GLSL shader fills/effects (editable source

package/corpus/templates/design/actions/clone-creative-context-design.ts

@@ -0,0 +1,176 @@
+import { defineAction } from "@agent-native/core";
+import { readAppState } from "@agent-native/core/application-state";
+import { assertAccess } from "@agent-native/core/sharing";
+import {
+  nativeCreativeArtifactFromMetadata,
+  reassembleNativeCreativeArtifact,
+} from "@agent-native/creative-context";
+import { recordGenerationCreativeContext } from "@agent-native/creative-context/server";
+import {
+  createContextPack,
+  getCreativeContextItem,
+  getCreativeContextItemByExternalId,
+} from "@agent-native/creative-context/store";
+import { z } from "zod";
+
+import {
+  resolveImportDesignId,
+  saveImportedDesignFiles,
+} from "../server/lib/import-design-files.js";
+
+export default defineAction({
+  description:
+    "Clone a version-pinned native Design artifact from the Creative Context library into the current Design project as editable HTML/CSS. Hierarchical Figma artboards are reassembled from their immutable child artifacts without AI regeneration.",
+  schema: z.object({
+    itemId: z.string().min(1).describe("Creative Context item id to clone."),
+    itemVersionId: z
+      .string()
+      .min(1)
+      .describe("Immutable item version id returned by get-context-item."),
+    designId: z
+      .string()
+      .optional()
+      .describe("Design id. Defaults to the active editor navigation state."),
+  }),
+  publicAgent: { expose: true, readOnly: false, requiresAuth: true },
+  run: async ({ itemId, itemVersionId, designId: explicitDesignId }) => {
+    const contextState = (await readAppState("creative-context").catch(
+      () => null,
+    )) as { contextMode?: "auto" | "off" } | null;
+    if (contextState?.contextMode === "off") {
+      throw new Error(
+        "Creative Context is off. Enable it before cloning a library design.",
+      );
+    }
+    const designId = await resolveImportDesignId(explicitDesignId);
+    await assertAccess("design", designId, "editor");
+    const root = await getCreativeContextItem(itemId, itemVersionId);
+    if (!root) {
+      throw new Error("Creative Context item or pinned version was not found.");
+    }
+    const rootArtifact = nativeCreativeArtifactFromMetadata(
+      root.version.metadata,
+    );
+    if (
+      !rootArtifact ||
+      rootArtifact.app !== "design" ||
+      rootArtifact.format !== "design-html"
+    ) {
+      throw new Error(
+        "Creative Context item is not an editable Design artifact.",
+      );
+    }
+    const reassembled = await reassembleNativeCreativeArtifact({
+      root,
+      app: "design",
+      format: "design-html",
+      resolveChild: getCreativeContextItemByExternalId,
+    });
+    const pack = await createContextPack({
+      name: `Clone: ${root.item.title}`.slice(0, 200),
+      contextMode: "manual",
+      request: {
+        operation: "clone-native-artifact",
+        appId: "design",
+        rootItemId: root.item.id,
+        rootItemVersionId: root.version.id,
+      },
+      members: reassembled.evidence.map((entry) => ({
+        ...entry,
+        reason: "Exact native artifact reuse",
+      })),
+    });
+    const saved = await saveImportedDesignFiles({
+      designId,
+      sourceType: "creative-context-clone",
+      preserveExactContent: true,
+      files: [
+        {
+          filename: `${safeFilename(root.item.title)}.html`,
+          fileType: "html",
+          content: reassembled.html,
+          source: {
+            sourceType: "creative-context",
+            contextPackId: pack.id,
+            itemId: root.item.id,
+            itemVersionId: root.version.id,
+            externalId: root.item.externalId,
+            sourceVersion: root.version.sourceVersion,
+          },
+          ...(reassembled.artifact.sourceBounds
+            ? {
+                preferredFrame: {
+                  title: root.item.title,
+                  width: reassembled.artifact.sourceBounds.width,
+                  height: reassembled.artifact.sourceBounds.height,
+                },
+              }
+            : {}),
+        },
+      ],
+    });
+    const savedFile = saved.files[0];
+    if (!savedFile) throw new Error("Design clone produced no saved file.");
+    const reuseLabels = reassembled.evidence.map((entry, index) => ({
+      ...entry,
+      kind: "native-artifact",
+      label:
+        entry.itemId === root.item.id
+          ? root.item.title
+          : `Native child ${index + 1}`,
+      dataRole: "untrusted-reference" as const,
+      elementId: `native-artifact:${index + 1}`,
+      influence: "reused" as const,
+    }));
+    await recordGenerationCreativeContext(
+      {
+        appId: "design",
+        artifactType: "design-file",
+        artifactId: savedFile.id,
+        contextMode: "pinned",
+        contextPackId: pack.id,
+        reuseLabels,
+        elementProvenance: reuseLabels.map((entry) => ({
+          elementId: entry.elementId,
+          influence: entry.influence,
+          itemId: entry.itemId,
+          itemVersionId: entry.itemVersionId,
+          label: entry.label,
+        })),
+      },
+      {
+        artifactAccess: { resourceType: "design", resourceId: designId },
+      },
+    );
+    return {
+      ...saved,
+      contextPackId: pack.id,
+      source: {
+        itemId: root.item.id,
+        itemVersionId: root.version.id,
+        evidenceCount: reassembled.evidence.length,
+      },
+      fidelityReport: reassembled.artifact.fidelityReport,
+      reusedWithoutRegeneration: true,
+    };
+  },
+  link: ({ result }) => {
+    if (!result || typeof result !== "object") return null;
+    const designId = (result as { designId?: string }).designId;
+    return designId
+      ? { url: `/design/${designId}`, label: "Open design", view: "editor" }
+      : null;
+  },
+});
+
+function safeFilename(value: string): string {
+  const normalized = value
+    .trim()
+    .replace(/\.[^.]+$/, "")
+    .replace(/[^A-Za-z0-9._ -]+/g, "-")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^[.-]+|[.-]+$/g, "")
+    .slice(0, 160);
+  return normalized || "creative-context-design";
+}

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

@@ -5,6 +5,13 @@ import {
   agentUpdateSelection,
 } from "@agent-native/core/collab";
 import { accessFilter, assertAccess } from "@agent-native/core/sharing";
+import {
+  getGenerationCreativeContext,
+  recordGenerationCreativeContext,
+  replaceCreativeContextElementProvenance,
+  validateGenerationCreativeContext,
+} from "@agent-native/creative-context/server";
+import type { CreativeContextReuseLabel } from "@agent-native/creative-context/types";
 import { and, eq } from "drizzle-orm";
 import { z } from "zod";
 
@@ -47,6 +54,18 @@ const editBlocksSchema = z.preprocess(
     .min(1),
 );
 
+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(),
+});
+
 function stripStableNodeIdAttributes(value: string): {
   content: string;
   indexMap: number[];
@@ -181,6 +200,21 @@ export default defineAction({
         .describe(
           "Complete updated file content. Use only with mode=replace-file for selected variant expansion or broad copy-only changes; preserve all HTML structure, CSS, scripts, and tweaks from get-design-snapshot. For selected variants, keep the replacement complete but compact instead of expanding secondary details into an oversized payload.",
         ),
+      contextPackId: z
+        .string()
+        .optional()
+        .describe("Exact Creative Context pack used for this file edit."),
+      contextModeOverride: z
+        .literal("off")
+        .optional()
+        .describe(
+          "Disable Creative Context for this edit only without changing the saved preference.",
+        ),
+      reuseLabels: z
+        .array(reuseLabelSchema)
+        .optional()
+        .default([])
+        .describe("Exact item versions that influenced this file edit."),
     })
     .superRefine((value, ctx) => {
       const mode =
@@ -223,6 +257,9 @@ export default defineAction({
     edits,
     mode,
     replacementContent,
+    contextPackId,
+    contextModeOverride,
+    reuseLabels,
   }) => {
     await assertAccess("design", designId, "editor");
 
@@ -296,7 +333,85 @@ export default defineAction({
         : applySearchReplaceEdits(base, edits ?? []);
     const changed = nextContent !== base;
 
+    let creativeContext:
+      | {
+          contextMode: "off" | "auto" | "pinned";
+          contextPackId: string | null;
+          reuseLabels: CreativeContextReuseLabel[];
+          elementProvenance: Array<{
+            elementId: string;
+            influence:
+              | "reused"
+              | "adapted"
+              | "reference-conditioned"
+              | "generated";
+            itemId?: string;
+            itemVersionId?: string;
+            label?: string;
+          }>;
+        }
+      | undefined;
+
     if (changed) {
+      const previous =
+        contextModeOverride === "off"
+          ? null
+          : await getGenerationCreativeContext({
+              appId: "design",
+              artifactType: "design",
+              artifactId: designId,
+            });
+      if (
+        contextPackId !== undefined &&
+        previous?.contextPackId &&
+        contextPackId !== previous.contextPackId
+      ) {
+        throw new Error(
+          "The design edit must preserve the design's creative-context pack",
+        );
+      }
+      const requestedLabels: CreativeContextReuseLabel[] = reuseLabels.length
+        ? reuseLabels
+        : [
+            {
+              kind: "design-file",
+              label: "Net-new design edit",
+              dataRole: "untrusted-reference",
+              elementId: file.id,
+              influence: "generated",
+            },
+          ];
+      const validated = await validateGenerationCreativeContext({
+        contextPackId: contextPackId ?? previous?.contextPackId,
+        contextPackSource:
+          contextPackId === undefined ? "inherited" : "explicit",
+        contextModeOverride,
+        reuseLabels: requestedLabels,
+        reuseLabelsSource: reuseLabels.length ? "explicit" : "inherited",
+      });
+      const elementProvenance = validated.reuseLabels.map((label) => ({
+        elementId: file.id,
+        influence: label.influence ?? ("reference-conditioned" as const),
+        ...(label.itemId ? { itemId: label.itemId } : {}),
+        ...(label.itemVersionId ? { itemVersionId: label.itemVersionId } : {}),
+        label: label.label,
+      }));
+      const contextMode =
+        validated.contextMode === "off"
+          ? "off"
+          : (previous?.contextMode ?? validated.contextMode);
+      creativeContext = {
+        contextMode,
+        contextPackId: validated.contextPackId,
+        reuseLabels: validated.reuseLabels,
+        elementProvenance:
+          contextMode === "off"
+            ? elementProvenance
+            : replaceCreativeContextElementProvenance(
+                previous?.elementProvenance ?? [],
+                elementProvenance,
+              ),
+      };
       assertLockedLayersPreserved(base, nextContent);
 
       // Mark agent presence + selection so live viewers can see where the
@@ -327,6 +442,12 @@ export default defineAction({
       } finally {
         agentLeaveDocument(file.id);
       }
+      await recordGenerationCreativeContext({
+        appId: "design",
+        artifactType: "design",
+        artifactId: designId,
+        ...creativeContext,
+      });
     }
 
     return {
@@ -338,6 +459,13 @@ export default defineAction({
       changed,
       bytesBefore: base.length,
       bytesAfter: nextContent.length,
+      ...(creativeContext
+        ? {
+            contextMode: creativeContext.contextMode,
+            contextPackId: creativeContext.contextPackId,
+            reuseLabels: creativeContext.reuseLabels,
+          }
+        : {}),
     };
   },
 });