@agent-native/core 0.87.0 → 0.90.1

package/corpus/templates/content/shared/source-component-block.ts

@@ -5,12 +5,56 @@ import {
 } from "@agent-native/core/blocks/server";
 import { z } from "zod";
 
+export type SourceComponentEditState =
+  | "safe-to-edit"
+  | "needs-review"
+  | "preserved-only";
+
+export type SourceComponentMappingStatus = "mapped" | "preserved" | "unknown";
+
+const sourceComponentMappingStatuses = [
+  "mapped",
+  "preserved",
+  "unknown",
+] as const satisfies readonly SourceComponentMappingStatus[];
+
+const sourceComponentEditStates = [
+  "safe-to-edit",
+  "needs-review",
+  "preserved-only",
+] as const satisfies readonly SourceComponentEditState[];
+
+const sourceComponentPreviewStatuses = [
+  "available",
+  "unavailable",
+  "warning",
+] as const satisfies readonly SourceComponentData["previewStatus"][];
+
+const sourceComponentPreviewKinds = [
+  "summary",
+  "table",
+  "embed",
+  "symbol",
+  "component",
+] as const satisfies readonly SourceComponentData["previewKind"][];
+
+function enumAttr<T extends string>(
+  value: string | undefined,
+  allowed: readonly T[],
+): T | undefined {
+  return allowed.includes(value as T) ? (value as T) : undefined;
+}
+
 export interface SourceComponentData {
   provider: string;
   componentName: string;
   rawRef: string;
   rawHash: string;
   sourceLabel?: string;
+  mappingId?: string;
+  mappingStatus?: SourceComponentMappingStatus;
+  mappingReason?: string;
+  sourceEditState?: SourceComponentEditState;
   previewStatus?: "available" | "unavailable" | "warning";
   previewKind?: "summary" | "table" | "embed" | "symbol" | "component";
   previewUrl?: string;
@@ -78,6 +122,12 @@ export const sourceComponentSchema = z.object({
   rawRef: z.string().trim().min(1),
   rawHash: z.string().trim().min(1),
   sourceLabel: z.string().trim().max(200).optional(),
+  mappingId: z.string().trim().max(120).optional(),
+  mappingStatus: z.enum(["mapped", "preserved", "unknown"]).optional(),
+  mappingReason: z.string().trim().max(1_000).optional(),
+  sourceEditState: z
+    .enum(["safe-to-edit", "needs-review", "preserved-only"])
+    .optional(),
   previewStatus: z.enum(["available", "unavailable", "warning"]).optional(),
   previewKind: z
     .enum(["summary", "table", "embed", "symbol", "component"])
@@ -97,6 +147,10 @@ export const sourceComponentMdx: BlockMdxConfig<SourceComponentData> = {
     rawRef: data.rawRef,
     rawHash: data.rawHash,
     sourceLabel: data.sourceLabel,
+    mappingId: data.mappingId,
+    mappingStatus: data.mappingStatus,
+    mappingReason: data.mappingReason,
+    sourceEditState: data.sourceEditState,
     previewStatus: data.previewStatus,
     previewKind: data.previewKind,
     previewUrl: data.previewUrl,
@@ -111,12 +165,24 @@ export const sourceComponentMdx: BlockMdxConfig<SourceComponentData> = {
     rawRef: attrs.string("rawRef") ?? "",
     rawHash: attrs.string("rawHash") ?? "",
     sourceLabel: attrs.string("sourceLabel"),
-    previewStatus: attrs.string("previewStatus") as
-      | SourceComponentData["previewStatus"]
-      | undefined,
-    previewKind: attrs.string("previewKind") as
-      | SourceComponentData["previewKind"]
-      | undefined,
+    mappingId: attrs.string("mappingId"),
+    mappingStatus: enumAttr(
+      attrs.string("mappingStatus"),
+      sourceComponentMappingStatuses,
+    ),
+    mappingReason: attrs.string("mappingReason"),
+    sourceEditState: enumAttr(
+      attrs.string("sourceEditState"),
+      sourceComponentEditStates,
+    ),
+    previewStatus: enumAttr(
+      attrs.string("previewStatus"),
+      sourceComponentPreviewStatuses,
+    ),
+    previewKind: enumAttr(
+      attrs.string("previewKind"),
+      sourceComponentPreviewKinds,
+    ),
     previewUrl: attrs.string("previewUrl"),
     previewItems: attrs.array<string>("previewItems"),
     preview: attrs.object<SourceComponentPreview>("preview"),

package/corpus/templates/content/vite.config.ts

@@ -317,12 +317,28 @@ function contentLocalComponentsPlugin(): Plugin {
         });
         return refreshPromise;
       };
+      // Coalesce rapid successive component-file writes (agents and editor
+      // atomic saves fire several add/unlink events per logical change) into
+      // a single full reload. Module invalidation stays immediate so the next
+      // request always sees fresh content.
+      let fullReloadTimer: ReturnType<typeof setTimeout> | null = null;
+      const scheduleFullReload = () => {
+        if (fullReloadTimer) clearTimeout(fullReloadTimer);
+        fullReloadTimer = setTimeout(() => {
+          fullReloadTimer = null;
+          server.ws.send({ type: "full-reload" });
+        }, 500);
+      };
+      server.httpServer?.once("close", () => {
+        if (fullReloadTimer) clearTimeout(fullReloadTimer);
+        fullReloadTimer = null;
+      });
       const invalidateComponents = (fullReload = false) => {
         const mod = server.moduleGraph.getModuleById(
           RESOLVED_LOCAL_COMPONENTS_MODULE_ID,
         );
         if (mod) server.moduleGraph.invalidateModule(mod);
-        if (fullReload) server.ws.send({ type: "full-reload" });
+        if (fullReload) scheduleFullReload();
       };
 
       await fs.promises.mkdir(registryDir, { recursive: true });

package/corpus/templates/design/.agents/skills/actions/SKILL.md

@@ -161,6 +161,18 @@ to find likely URLs, `web-request` or `provider-api-docs` with clean
 `webFetch()` when you need to grep, aggregate, or compare many pages before
 returning a small result.
 
+For LONG compute, `run-code` supports durable background executions: pass
+`background: true` and the code is enqueued to a `sandbox_executions` row and
+executed out-of-band with a generous budget (default 10 min), surviving the
+hosted agent run's ~40s soft timeout. The call returns
+`{ executionId, status: "queued" }` immediately with polling guidance; check
+progress with `run-code` `{ executionId }` (or the `get-code-execution` tool
+where registered) — results persist after completion. Use background for big
+cross-source joins, multi-page provider sweeps, and heavy analysis scripts;
+keep quick scripts in the default foreground mode. Agents should continue
+other work between polls, and on `failed`/`timed_out` split the computation or
+persist intermediate progress with `workspaceWrite` and re-run.
+
 ### The `http` Option
 
 Controls how the action is exposed as an HTTP endpoint:
@@ -205,6 +217,49 @@ run: async (args) => {
 }
 ```
 
+### Returning Images the Agent Can See (`_agentImages`)
+
+An action's return object may include the well-known optional field
+`_agentImages` to attach vision images (screenshots, chart previews, rendered
+designs) to the tool result. The agent literally sees them — enabling visual
+self-review loops — while the field itself is stripped from the JSON text the
+model reads.
+
+```ts
+run: async ({ dashboardId }) => {
+  const shot = await renderDashboardPng(dashboardId); // Buffer
+  return {
+    dashboardId,
+    panelCount: 6,
+    _agentImages: [
+      // Either a public https URL (preferred — the provider fetches it)…
+      { url: "https://cdn.example.com/previews/dash-1.png", label: "overview" },
+      // …or base64 without a data: prefix (mediaType required; a full
+      // data:image/png;base64,… URL in `data` is also accepted and parsed).
+      { data: shot.toString("base64"), mediaType: "image/png" },
+    ],
+  };
+},
+```
+
+Rules and limits:
+
+- Shape: `Array<{ url?: string; data?: string; mediaType?: string; label?: string }>`.
+  Each entry needs `url` (https only) **or** `data`. Supported media types:
+  `image/jpeg`, `image/png`, `image/gif`, `image/webp`.
+- Caps: max **4 images** per result; max **~2MB of base64** per image.
+  Over-cap or invalid entries never fail the call — they become text notes in
+  the result telling the model what was dropped and why.
+- Persistence: the run ledger stores only the string result plus compact
+  `[image: …]` notes (URLs verbatim; base64 as a byte-count placeholder) —
+  never the payload. Images are re-attached only for the live turn; replayed
+  history is text-only, so prefer stable `url` images the model can re-request.
+- Engine support: native Anthropic and vision-capable AI-SDK providers
+  (anthropic, openai, google, openrouter) receive real image blocks; other
+  paths (Builder gateway, non-vision providers) degrade to the text notes.
+- External MCP tools need no changes — standard MCP `image` content parts are
+  converted automatically under the same caps.
+
 ### Validating Return Values (`outputSchema`)
 
 `schema` validates inputs; `outputSchema` validates what the action **returns**. Pass any Standard Schema-compatible schema (Zod, Valibot, ArkType) and the framework validates the result _after_ `run()` resolves — input validated before `run`, output after.

package/corpus/templates/design/.agents/skills/design-generation/SKILL.md

@@ -248,21 +248,30 @@ pnpm action generate-design \
 
 `generate-design` accepts a `--tweaks` array — pass 3-6 of the most impactful knobs bound to CSS custom properties the design's `:root` block actually defines. Surface controls users will actually want to adjust (accent color, density, radius, dark-mode toggle, font choice). Don't ship a generic preset; let the design's structure pick the knobs.
 
-### Phase 5 — Audit, fix, and eyeball before calling it ready
+### Phase 5 — Audit, screenshot, fix, and eyeball before calling it ready
 
 Run `run-design-audit` against each screen (`designId` + `fileId`/`filename`).
 It returns `A11yFinding[]` covering missing alt/labels, tap-target size,
-focus-visibility, reduced-motion coverage, and a contrast hint. For every
-`error`-severity finding with `fixAvailable: true`, call `apply-a11y-fix`;
-for findings that aren't auto-fixable (missing alt text, structural issues),
-fix them directly with `edit-design`. **A design with audit errors is not
-ready** — don't report a design as done while `run-design-audit` still
-returns unresolved errors.
-
-After the audit is clean, do one visual pass by eye at both a mobile width
-(375px) and a desktop width (1280px): check for overflow/clipping, broken
-hierarchy, empty/loading/error states for app UI, and whether the copy/content
-still sounds real. Fix obvious issues before reporting the design as ready.
+focus-visibility, reduced-motion coverage, a contrast hint, and — for
+multi-screen designs — token drift against `index.html`'s `:root` block. For
+every `error`-severity finding with `fixAvailable: true`, call
+`apply-a11y-fix`; for findings that aren't auto-fixable (missing alt text,
+structural issues, token drift), fix them directly with `edit-design`. **A
+design with audit errors is not ready** — don't report a design as done while
+`run-design-audit` still returns unresolved errors.
+
+After the audit is clean, call `take-design-screenshot` on each changed screen
+(default: 1280px desktop + 375px mobile). Fix everything its `diagnostics`
+report flags — real computed contrast ratios, horizontal/container overflow,
+broken images, zero-size or off-screen text, console errors — before reporting
+the design as ready; this is the same "visually inspect the result" pass, done
+against the real rendered DOM/CSS instead of by eye. If Chromium isn't
+available in the current environment, it returns `{ ok: false, reason }`
+instead — fall back to a careful read of the HTML plus the audit findings. The
+returned screenshot `url` is for human review (embed it as `![...](url)` in
+your reply); also still scan the rendered output yourself for anything the
+diagnostics don't catch — broken hierarchy, empty/loading/error states for app
+UI, and whether the copy/content still sounds real.
 
 ## HTML Structure Requirements
 

package/corpus/templates/design/AGENTS.md

@@ -30,8 +30,9 @@ patterns live in `.agents/skills/`.
   screens, linked design systems, tokens, and component language before
   inventing a new direction. Use realistic content/copy and one signature choice
   per direction; avoid lorem ipsum, generic SaaS filler, and decorative
-  placeholders. Include expected responsive/accessibility states and visually
-  inspect the result before calling it ready.
+  placeholders. Include expected responsive/accessibility states, run
+  `run-design-audit`, and call `take-design-screenshot` on each changed screen
+  before calling it ready — see the `design-generation` skill's Phase 5.
 - For editable reusable building blocks inside Design, use
   `list-design-native-assets` first, then `insert-design-native-asset` with the
   chosen kind. These are Design-native HTML primitives/components, not external

package/corpus/templates/design/actions/import-design-source.ts

@@ -2,14 +2,12 @@ import { defineAction } from "@agent-native/core";
 import { assertAccess } from "@agent-native/core/sharing";
 import { z } from "zod";
 
-import { parseFigmaClipboardHtml } from "../server/lib/figma-import/clipboard.js";
-import { importFigmaBuffer } from "../server/lib/figma-import/processor.js";
 import {
   normalizeImportedHtmlDocument,
   resolveImportDesignId,
   saveImportedDesignFiles,
-  type ImportedDesignFile,
 } from "../server/lib/import-design-files.js";
+import { parseVisibleClipboardHtml } from "../server/lib/visible-clipboard-html.js";
 
 const MAX_HTML_IMPORT_BYTES = 2 * 1024 * 1024;
 
@@ -25,7 +23,7 @@ function baseFilename(originalName: string | undefined, fallback: string) {
 
 export default defineAction({
   description:
-    "Import Figma clipboard HTML or standalone HTML into the current Design project as one or more editable screens.",
+    "Import visible clipboard HTML or standalone HTML into the current Design project as an editable screen.",
   schema: z.object({
     designId: z
       .string()
@@ -64,84 +62,36 @@ export default defineAction({
       };
     }
 
-    const parsed = parseFigmaClipboardHtml(content);
-    const warnings: string[] = [];
-    if (parsed.buffer && parsed.hasFigmaBuffer) {
-      try {
-        const imported = await importFigmaBuffer({
-          buffer: parsed.buffer,
-          filename: originalName ?? "figma-paste.fig",
-          sourceKind: "figma-paste",
-          selection: { nodeId: parsed.meta?.selectedNodeId },
-          meta: parsed.meta,
-        });
-        const files: ImportedDesignFile[] = imported.files.map((file) => ({
-          filename: file.filename,
-          fileType: "html",
-          content: file.content,
-          source: file.source,
-          preferredFrame: {
-            title:
-              typeof file.source?.frameName === "string"
-                ? file.source.frameName
-                : undefined,
-            width: file.width,
-            height: file.height,
-          },
-        }));
-        const saved = await saveImportedDesignFiles({
-          designId: resolvedDesignId,
-          sourceType: "figma-paste",
-          files,
-          warnings: [...warnings, ...imported.warnings],
-        });
-        return { ...saved, stats: imported.stats };
-      } catch (error) {
-        warnings.push(
-          error instanceof Error
-            ? `Figma binary payload could not be decoded: ${error.message}`
-            : "Figma binary payload could not be decoded.",
-        );
-      }
-    } else if (parsed.buffer) {
-      warnings.push(
-        "The clipboard included a Figma buffer, but it was not a supported fig-kiwi payload.",
-      );
-    }
-
+    const parsed = parseVisibleClipboardHtml(content);
     if (!parsed.fallbackHtml) {
       throw new Error(
-        "No importable Figma frame data or visible HTML was found in the clipboard.",
+        "No visible HTML was found in the clipboard. Copy a frame, then paste into the canvas.",
       );
     }
     const saved = await saveImportedDesignFiles({
       designId: resolvedDesignId,
-      sourceType: "figma-paste-fallback",
+      sourceType: "figma-paste-html",
       files: [
         {
           filename: baseFilename(originalName, "figma-paste"),
           fileType: "html",
           content: normalizeImportedHtmlDocument(
             parsed.fallbackHtml,
-            "Figma clipboard fallback HTML",
+            "visible clipboard HTML",
           ),
           source: {
-            sourceType: "figma-paste-fallback",
-            selectedNodeId: parsed.meta?.selectedNodeId,
-            fileKey: parsed.meta?.fileKey,
+            sourceType: "figma-paste-html",
           },
         },
       ],
-      warnings,
     });
     return {
       ...saved,
       stats: {
         sourceKind: "figma-paste",
-        format: "html-fallback",
+        format: "html",
         frameCount: saved.files.length,
         imageCount: 0,
-        selectedNodeId: parsed.meta?.selectedNodeId,
       },
     };
   },

package/corpus/templates/design/actions/run-design-audit.ts

@@ -380,6 +380,93 @@ function checkContrastHint(html: string): A11yFinding[] {
   return findings;
 }
 
+// ---------------------------------------------------------------------------
+// Multi-screen token-drift check
+// ---------------------------------------------------------------------------
+//
+// design-generation/SKILL.md's "Multi-screen consistency contract" requires
+// every screen's `:root` token block to match index.html's byte-for-byte, but
+// nothing enforced it — an agent could silently let a screen's palette drift.
+// This extracts each screen's `:root { --name: value; ... }` custom-property
+// map and flags any screen whose property VALUES diverge from the design's
+// reference screen (index.html, or the first screen when index.html is
+// absent). Screens that legitimately have no `:root` block (e.g. a bare
+// fragment) are skipped, not flagged — there is nothing to reconcile.
+
+/** One screen's parsed `:root` custom-property map (property name → value). */
+export interface RootTokenMap {
+  filename: string;
+  tokens: Record<string, string>;
+}
+
+/**
+ * Extract the FIRST `:root { ... }` block's custom properties from a screen's
+ * HTML. Returns an empty map (not an error) when no `:root` block is present —
+ * callers treat that as "nothing to compare" rather than a finding.
+ */
+export function extractRootTokens(html: string): Record<string, string> {
+  const tokens: Record<string, string> = {};
+  const rootMatch = html.match(/:root\s*\{([^}]*)\}/i);
+  if (!rootMatch) return tokens;
+  const body = rootMatch[1] ?? "";
+  const declPattern = /(--[a-zA-Z0-9-]+)\s*:\s*([^;]+);/g;
+  let m: RegExpExecArray | null;
+  while ((m = declPattern.exec(body)) !== null) {
+    const name = m[1]?.trim();
+    const value = m[2]?.trim();
+    if (name && value !== undefined) tokens[name] = value;
+  }
+  return tokens;
+}
+
+/**
+ * Compare every non-reference screen's `:root` token map against the
+ * reference screen's (normally `index.html`) and return one finding per
+ * diverging property per screen. Screens with no `:root` block are skipped.
+ * Pure and dependency-free so it can be unit tested without a DB.
+ */
+export function checkTokenDrift(
+  screens: Array<{ filename: string; html: string }>,
+  referenceFilename = "index.html",
+): A11yFinding[] {
+  const findings: A11yFinding[] = [];
+  if (screens.length < 2) return findings;
+
+  const reference =
+    screens.find((s) => s.filename === referenceFilename) ?? screens[0];
+  const referenceTokens = extractRootTokens(reference.html);
+  if (Object.keys(referenceTokens).length === 0) return findings;
+
+  let idx = 0;
+  for (const screen of screens) {
+    if (screen.filename === reference.filename) continue;
+    const screenTokens = extractRootTokens(screen.html);
+    // No :root block on this screen — nothing to reconcile, not a finding.
+    if (Object.keys(screenTokens).length === 0) continue;
+
+    for (const [property, referenceValue] of Object.entries(referenceTokens)) {
+      const screenValue = screenTokens[property];
+      if (screenValue === undefined || screenValue === referenceValue) {
+        continue;
+      }
+      findings.push({
+        id: `token-drift:${screen.filename}:${property}-${idx}`,
+        severity: "warning" as A11ySeverity,
+        category: "token-drift" as A11yFindingCategory,
+        message: `"${property}" diverges from ${reference.filename} on ${screen.filename}.`,
+        detail:
+          `${reference.filename} defines ${property}: ${referenceValue}; ` +
+          `${screen.filename} defines ${property}: ${screenValue}. Reconcile ` +
+          `the :root token block so every screen shares one design system.`,
+        selector: ":root",
+        fixAvailable: false,
+      });
+      idx++;
+    }
+  }
+  return findings;
+}
+
 // ---------------------------------------------------------------------------
 // Live-content helper (matches the pattern in other actions)
 // ---------------------------------------------------------------------------
@@ -407,7 +494,9 @@ export default defineAction({
   description:
     "Run a read-only accessibility audit over a design's rendered HTML. " +
     "Checks contrast hints, tap-target sizes, missing alt attributes, missing " +
-    "form labels, focus-visibility gaps, and reduced-motion coverage. " +
+    "form labels, focus-visibility gaps, reduced-motion coverage, and — for " +
+    "multi-screen designs — token drift (the audited screen's :root custom " +
+    "properties diverging from index.html's). " +
     "Returns A11yFinding[] that can be shown in the Review panel or persisted " +
     "via create-design-review-snapshot. No writes are performed.",
   schema: z.object({
@@ -465,6 +554,42 @@ export default defineAction({
 
     const html = await liveContent(file.id, file.content ?? "");
 
+    // Load every other HTML screen in the design (id + filename only) so the
+    // token-drift check can compare :root blocks across the whole design, not
+    // just the audited screen. Cheap: same table, no content fetched twice.
+    const otherHtmlFiles = await db
+      .select({
+        id: schema.designFiles.id,
+        filename: schema.designFiles.filename,
+        content: schema.designFiles.content,
+      })
+      .from(schema.designFiles)
+      .where(
+        and(
+          eq(schema.designFiles.designId, designId),
+          eq(schema.designFiles.fileType, "html"),
+        ),
+      );
+
+    const screens = await Promise.all(
+      otherHtmlFiles.map(async (f) => ({
+        filename: f.filename,
+        html:
+          f.id === file.id ? html : await liveContent(f.id, f.content ?? ""),
+      })),
+    );
+
+    // Token drift is inherently cross-screen. When the audited screen IS the
+    // reference (index.html), surface drift for every other screen; otherwise
+    // scope findings to just the audited screen so a per-screen audit call
+    // doesn't report unrelated screens' drift.
+    const isReferenceScreen = file.filename === "index.html";
+    const tokenDriftFindings = checkTokenDrift(screens).filter(
+      (finding) =>
+        isReferenceScreen ||
+        finding.id.includes(`token-drift:${file.filename}:`),
+    );
+
     // Run all audit checks over the static HTML.
     const findings: A11yFinding[] = [
       ...checkMissingAlt(html),
@@ -473,6 +598,7 @@ export default defineAction({
       ...checkReducedMotion(html),
       ...checkFocusVisibility(html),
       ...checkContrastHint(html),
+      ...tokenDriftFindings,
     ];
 
     // Summarise by severity for the agent context.