@agent-native/core 0.153.9 → 0.154.0

package/corpus/templates/design/actions/index-design-system-with-builder.ts

@@ -10,7 +10,6 @@ import {
 import { z } from "zod";
 
 import { upsertBuilderProxyDesignSystem } from "../server/lib/builder-design-system-proxy.js";
-import importGithub from "./import-github.js";
 
 const codeFileSchema = z.object({
   filename: z.string().trim().min(1).describe("File name or relative path"),
@@ -33,6 +32,30 @@ const codeFileSchema = z.object({
     ),
 });
 
+const githubSourceSchema = z.object({
+  repoUrl: z.string().trim().min(1).describe("GitHub repository URL"),
+  ref: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe("Optional branch, tag, or commit"),
+  include: z
+    .array(z.string().trim().min(1))
+    .optional()
+    .describe("Optional repository-relative files or folders to include"),
+  exclude: z
+    .array(z.string().trim().min(1))
+    .optional()
+    .describe("Optional repository-relative files or folders to exclude"),
+  instructions: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe("Optional indexing guidance for this repository"),
+});
+
 export default defineAction({
   description:
     "Start Builder DSI design-system indexing from connected code, a GitHub repository, code/design files, and optional design.md guidance. " +
@@ -51,7 +74,15 @@ export default defineAction({
     githubRepoUrl: z
       .string()
       .optional()
-      .describe("GitHub repository URL to index with Builder"),
+      .describe("Legacy single GitHub repository URL to index with Builder"),
+    githubSources: z
+      .array(githubSourceSchema)
+      .min(1)
+      .max(20)
+      .optional()
+      .describe(
+        "GitHub repositories to index in one design system. Each source may specify a branch/tag/commit and repository-relative files or folders.",
+      ),
     connectedProjectId: z
       .string()
       .optional()
@@ -71,21 +102,13 @@ export default defineAction({
     projectName,
     description,
     githubRepoUrl,
+    githubSources,
     connectedProjectId,
     codeFiles,
     designMd,
   }) => {
-    const githubImport = githubRepoUrl
-      ? await importGithub.run({ repoUrl: githubRepoUrl })
-      : null;
-    const githubFiles = githubImport?.rawFiles
-      ? Object.entries(githubImport.rawFiles).map(([filename, content]) => ({
-          filename,
-          content,
-        }))
-      : [];
     const files = buildBuilderDesignSystemIndexFiles({
-      codeFiles: [...(codeFiles ?? []), ...githubFiles],
+      codeFiles,
       designMd,
       // Agent action payloads intentionally stay at the core 2 MB inline
       // budget. Fail loudly instead of silently dropping a larger `.fig`;
@@ -95,10 +118,8 @@ export default defineAction({
     const result = await startBuilderDesignSystemIndex({
       projectName,
       description,
-      // Upload token-authenticated GitHub files as Builder file sources. If
-      // there was nothing relevant to upload, retain the public-repo source
-      // so public repositories still work without a saved token.
-      githubRepoUrl: githubFiles.length > 0 ? undefined : githubRepoUrl,
+      githubRepoUrl,
+      githubRepos: githubSources,
       connectedProjectId,
       files,
     });
@@ -111,12 +132,24 @@ export default defineAction({
       orgId: getRequestOrgId(),
       projectName,
       description,
+      githubSources:
+        githubSources ?? (githubRepoUrl ? [{ repoUrl: githubRepoUrl }] : []),
+      sourceKind:
+        (githubSources?.length || githubRepoUrl) &&
+        (codeFiles?.length || designMd)
+          ? "mixed"
+          : githubSources?.length || githubRepoUrl
+            ? "github"
+            : codeFiles?.length || designMd
+              ? "code"
+              : undefined,
     });
 
     return {
       ...result,
       ...proxy,
       uploadedFileCount: files.length,
+      githubSourceCount: githubSources?.length ?? (githubRepoUrl ? 1 : 0),
     };
   },
 });

package/corpus/templates/design/actions/present-design-variants.ts

@@ -46,6 +46,49 @@ const DEFAULT_RESPONSIVE_BREAKPOINTS = [MOBILE_WIDTH].map((widthPx) => ({
   prefix: widthToPrefix(widthPx),
 }));
 
+const SPECIFICATION_SIGNAL_PATTERNS = [
+  /\b(?:attached|uploaded|reference|mockup|screenshot|wireframe|source of truth|source-of-truth)\b/i,
+  /\b(?:\d+\s*[- ]\s*col(?:umn)?|grid spec|layout spec|section order|feature list)\b/i,
+  /\b(?:design system|brand system|brand kit|visual language|tokens?)\b/i,
+] as const;
+
+/**
+ * Direction summaries are useful for genuinely open-ended exploration, but
+ * the fallback renderer cannot reproduce a supplied layout or system. Keep a
+ * complete-HTML requirement at the action boundary so a model cannot turn a
+ * detailed screen brief into generic cards just by omitting `content`.
+ *
+ * The weakest of the two signals, and never the only one: `prompt` is the chat
+ * caption this same model writes for the picker, so an agent that has just
+ * decided to explore writes an exploration-flavored caption and clears the
+ * check for free. `hasLinkedDesignSystem` below is the fact the server owns.
+ */
+export function hasSpecifiedDesignPrompt(prompt?: string): boolean {
+  const value = prompt?.trim() ?? "";
+  if (!value) return false;
+  return SPECIFICATION_SIGNAL_PATTERNS.some((pattern) => pattern.test(value));
+}
+
+/**
+ * The one specification signal that survives an intake round-trip. Attachments
+ * are turn-scoped (see `ActionRunContext.attachments`), so by the time the
+ * agent asks its questions and comes back to present variants, the reference
+ * screenshot the user supplied is no longer visible to this action — but the
+ * design system they linked still is.
+ */
+async function hasLinkedDesignSystem(designId: string): Promise<boolean> {
+  const [design] = await getDb()
+    .select({ designSystemId: schema.designs.designSystemId })
+    .from(schema.designs)
+    .where(
+      and(
+        eq(schema.designs.id, designId),
+        accessFilter(schema.designs, schema.designShares),
+      ),
+    );
+  return Boolean(design?.designSystemId?.trim());
+}
+
 function hasBreakpointSet(value: unknown): boolean {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return false;
@@ -114,7 +157,7 @@ const variantSchema = z.object({
     .string()
     .optional()
     .describe(
-      "Optional complete self-contained HTML document for this variant. Keep it compact: one representative screen or directional snapshot, not a full multi-screen app. For faster exploration, omit this and provide label/description/features; Design will generate a compact representative screen.",
+      "Complete self-contained HTML document for this variant. Keep it compact: one representative screen or directional snapshot, not a full multi-screen app. Omit it ONLY for genuinely open-ended exploration, where Design renders a generic direction card from label/description/features — that card ignores any supplied reference, layout, or design system, so omitting content is rejected when the design has a linked design system or the prompt specifies one.",
     ),
   width: z
     .number()
@@ -825,9 +868,12 @@ export default defineAction({
     "complex apps, " +
     "make each variant a " +
     "compact representative screen; pass concise labels/descriptions/features " +
-    "and omit content when full HTML would be too large. Design will render " +
-    "compact screens from the direction data. Expand the chosen direction " +
-    "after the user picks. Screens from an earlier variant set are never " +
+    "and omit content only for open-ended exploration. For a prompt with a " +
+    "specific product surface, reference, layout, or design system, provide " +
+    "complete self-contained HTML for every variant; the generic fallback is " +
+    "blocked there. Design will render compact screens from direction data only " +
+    "for open-ended exploration. Expand the chosen direction after the user " +
+    "picks. Screens from an earlier variant set are never " +
     "deleted automatically: if you are knowingly replacing your own earlier " +
     "set that the user never picked from or discussed, pass its set id in " +
     "deleteSupersededSetIds; otherwise leave old sets in place.",
@@ -872,6 +918,24 @@ export default defineAction({
   run: async ({ designId, prompt, variants, deleteSupersededSetIds }) => {
     await assertAccess("design", designId, "editor");
 
+    const omittedContent = variants.filter(
+      (variant) => !variant.content?.trim(),
+    );
+    if (
+      omittedContent.length > 0 &&
+      (hasSpecifiedDesignPrompt(prompt) ||
+        (await hasLinkedDesignSystem(designId)))
+    ) {
+      throw new Error(
+        "present-design-variants requires complete self-contained HTML for " +
+          "every variant when the design has a linked design system, or the " +
+          "prompt specifies a layout, reference, or product surface. The " +
+          "generic direction fallback ignores the brief and the system's " +
+          "tokens; use generate-design, or provide each variant's complete " +
+          "content.",
+      );
+    }
+
     // Before any mutation. These are model-authored screens created by raw
     // insert, so they need the same well-formedness gate as generate-design —
     // though not its document-shape rules, since a variant may be a sketch with
@@ -1089,7 +1153,32 @@ export default defineAction({
       editorView: "overview",
       path: `/design/${encodeURIComponent(designId)}?view=overview`,
     });
+    // The pick opens a continuation turn that inherits nothing from this one,
+    // and that turn is what expands the kept placeholder into the real screen.
+    // Without this, the expansion is design-system-blind even though the user
+    // linked one before generating.
+    const [linkedDesign] = await db
+      .select({ designSystemId: schema.designs.designSystemId })
+      .from(schema.designs)
+      .where(
+        and(
+          eq(schema.designs.id, designId),
+          accessFilter(schema.designs, schema.designShares),
+        ),
+      );
+    const variantPickContext = [
+      prompt?.trim()
+        ? `The user's original request for this design: "${prompt.trim()}". Expand the kept direction into that, not into a generic version of it.`
+        : "",
+      linkedDesign?.designSystemId
+        ? `This design is linked to design system "${linkedDesign.designSystemId}". Call \`get-design-system\` for that id and apply its tokens, typography, and usage notes while expanding the kept screen — do not substitute a generic palette or font.`
+        : "",
+    ]
+      .filter(Boolean)
+      .join("\n");
+
     await writeAppStateForCurrentTab("guided-questions", {
+      ...(variantPickContext ? { submitContext: variantPickContext } : {}),
       title: prompt ?? "Pick a direction",
       description:
         "All options are on the board. Choose one to keep; I will delete the others, read only the kept screen, and turn that direction into the final requested screen.",

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

@@ -489,6 +489,203 @@ export function checkTokenDrift(
   return findings;
 }
 
+// ---------------------------------------------------------------------------
+// Design-system adherence check
+// ---------------------------------------------------------------------------
+//
+// checkTokenDrift above only proves the screens agree with EACH OTHER. A design
+// can be perfectly self-consistent and still ignore the brand it is linked to,
+// which is the most-reported failure of generation: the user links their system,
+// the agent writes its own palette, and nothing anywhere notices. This compares
+// the saved HTML against the linked kit's own values so the drift is reportable
+// instead of invisible.
+
+/** The subset of a Brand Kit this check can verify against rendered HTML. */
+export interface DesignSystemExpectation {
+  title: string;
+  fonts: string[];
+  /** Lowercase six-digit hex values, normalized from the kit's own notation. */
+  colors: string[];
+  /** Custom-property names the kit names, e.g. `--color-primary`. */
+  cssVars: string[];
+  /**
+   * The kit's stored `data` could not be parsed. Adherence is then UNKNOWN,
+   * which is not the same as satisfied — a silent empty expectation would
+   * report a corrupt design system as a clean audit.
+   */
+  unreadable?: boolean;
+}
+
+function normalizeHex(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const match = value.trim().match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i);
+  if (!match) return null;
+  const hex = match[1].toLowerCase();
+  // Expand shorthand so 3- and 6-digit forms compare in one space.
+  return hex.length === 3
+    ? `#${hex[0]}${hex[0]}${hex[1]}${hex[1]}${hex[2]}${hex[2]}`
+    : `#${hex}`;
+}
+
+function expandShortHexes(html: string): string {
+  return html.replace(
+    /#([0-9a-f])([0-9a-f])([0-9a-f])\b/gi,
+    (_m, r: string, g: string, b: string) =>
+      `#${r}${r}${g}${g}${b}${b}`.toLowerCase(),
+  );
+}
+
+/**
+ * Build the checkable expectation from a kit's stored `data` JSON. Returns null
+ * when the kit carries nothing verifiable — "we cannot check" must not render
+ * as "the design complies".
+ */
+export function designSystemExpectation(
+  title: string,
+  data: string | null | undefined,
+): DesignSystemExpectation | null {
+  const unreadable: DesignSystemExpectation = {
+    title,
+    fonts: [],
+    colors: [],
+    cssVars: [],
+    unreadable: true,
+  };
+  let parsed: Record<string, unknown> | null = null;
+  try {
+    parsed = data ? (JSON.parse(data) as Record<string, unknown>) : null;
+  } catch {
+    return unreadable;
+  }
+  if (!parsed) return null;
+
+  const typography = (parsed.typography ?? {}) as Record<string, unknown>;
+  const fonts = [typography.headingFont, typography.bodyFont]
+    .filter((font): font is string => typeof font === "string" && !!font.trim())
+    .map((font) => font.trim());
+
+  const colorRoles = (parsed.colors ?? {}) as Record<string, unknown>;
+  const colors = Object.values(colorRoles)
+    .map(normalizeHex)
+    .filter((hex): hex is string => hex !== null);
+
+  const cssVars = Array.isArray(parsed.tokens)
+    ? parsed.tokens
+        .map((token) =>
+          token && typeof token === "object"
+            ? (token as { cssVar?: unknown }).cssVar
+            : null,
+        )
+        .filter(
+          (cssVar): cssVar is string =>
+            typeof cssVar === "string" && cssVar.startsWith("--"),
+        )
+    : [];
+
+  if (fonts.length === 0 && colors.length === 0 && cssVars.length === 0) {
+    return null;
+  }
+  return {
+    title,
+    fonts: Array.from(new Set(fonts)),
+    colors: Array.from(new Set(colors)),
+    cssVars: Array.from(new Set(cssVars)),
+  };
+}
+
+/**
+ * Flag a screen that uses none of its linked design system's fonts, or none of
+ * its colors. Deliberately a "none of them" test rather than a per-value one:
+ * a design legitimately uses a subset of a kit, but a design using zero of it
+ * is not following it at all. Pure so it can be unit tested without a DB.
+ */
+export function checkDesignSystemAdherence(
+  html: string,
+  expectation: DesignSystemExpectation | null,
+  filename: string,
+): A11yFinding[] {
+  if (!expectation) return [];
+  if (expectation.unreadable) {
+    return [
+      {
+        id: `design-system-drift:${filename}:unreadable`,
+        severity: "warning",
+        category: "design-system-drift",
+        message: `"${expectation.title}" could not be read, so adherence was not checked.`,
+        detail:
+          "The linked design system's stored token data is not valid JSON. " +
+          "Adherence is unknown, not satisfied — re-import or re-index the " +
+          "system before treating this screen as on-brand.",
+        selector: ":root",
+        fixAvailable: false,
+      },
+    ];
+  }
+  const findings: A11yFinding[] = [];
+  const haystack = expandShortHexes(html.toLowerCase());
+
+  if (expectation.fonts.length > 0) {
+    const used = expectation.fonts.filter((font) =>
+      haystack.includes(font.toLowerCase()),
+    );
+    if (used.length === 0) {
+      findings.push({
+        id: `design-system-drift:${filename}:fonts`,
+        severity: "warning",
+        category: "design-system-drift",
+        message: `${filename} uses none of "${expectation.title}"'s fonts.`,
+        detail:
+          `The linked design system specifies ${expectation.fonts.join(", ")}, ` +
+          `but ${filename} references none of them. Load and apply the system's ` +
+          "typography, or tell the user you are deviating and why.",
+        selector: ":root",
+        fixAvailable: false,
+      });
+    }
+  }
+
+  if (expectation.colors.length > 0) {
+    const used = expectation.colors.filter((hex) => haystack.includes(hex));
+    if (used.length === 0) {
+      findings.push({
+        id: `design-system-drift:${filename}:colors`,
+        severity: "warning",
+        category: "design-system-drift",
+        message: `${filename} uses none of "${expectation.title}"'s colors.`,
+        detail:
+          `The linked design system defines ${expectation.colors.slice(0, 6).join(", ")}` +
+          `${expectation.colors.length > 6 ? ", …" : ""}, but ${filename} uses none of ` +
+          "them. Put the system's values in the `:root` token block instead of an " +
+          "invented palette.",
+        selector: ":root",
+        fixAvailable: false,
+      });
+    }
+  }
+
+  if (expectation.cssVars.length > 0) {
+    const used = expectation.cssVars.filter((cssVar) =>
+      haystack.includes(cssVar.toLowerCase()),
+    );
+    if (used.length === 0) {
+      findings.push({
+        id: `design-system-drift:${filename}:css-vars`,
+        severity: "info",
+        category: "design-system-drift",
+        message: `${filename} uses none of "${expectation.title}"'s token names.`,
+        detail:
+          `The system names ${expectation.cssVars.length} custom properties (e.g. ` +
+          `${expectation.cssVars.slice(0, 4).join(", ")}). Reusing those exact names ` +
+          "keeps the prototype swappable with the real codebase.",
+        selector: ":root",
+        fixAvailable: false,
+      });
+    }
+  }
+
+  return findings;
+}
+
 // ---------------------------------------------------------------------------
 // Live-content helper (matches the pattern in other actions)
 // ---------------------------------------------------------------------------
@@ -519,6 +716,11 @@ export default defineAction({
     "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). " +
+    "When the design is linked to a design system, also reports " +
+    "design-system drift: the screen using none of the linked system's fonts, " +
+    "colors, or token names. Treat that finding as a generation bug to fix, " +
+    "not a style opinion — reload the system with `get-design-system` and " +
+    "apply its values rather than explaining the deviation. " +
     "Returns A11yFinding[] that can be shown in the Review panel or persisted " +
     "via create-design-review-snapshot. No writes are performed.",
   schema: z.object({
@@ -612,6 +814,32 @@ export default defineAction({
         finding.id.includes(`token-drift:${file.filename}:`),
     );
 
+    // Adherence to the LINKED system, which token drift cannot see.
+    const [linkedSystem] = await db
+      .select({
+        title: schema.designSystems.title,
+        data: schema.designSystems.data,
+      })
+      .from(schema.designs)
+      .innerJoin(
+        schema.designSystems,
+        eq(schema.designs.designSystemId, schema.designSystems.id),
+      )
+      .where(
+        and(
+          eq(schema.designs.id, designId),
+          accessFilter(schema.designSystems, schema.designSystemShares),
+        ),
+      )
+      .limit(1);
+    const designSystemFindings = linkedSystem
+      ? checkDesignSystemAdherence(
+          html,
+          designSystemExpectation(linkedSystem.title, linkedSystem.data),
+          file.filename,
+        )
+      : [];
+
     // Run all audit checks over the static HTML.
     const findings: A11yFinding[] = [
       ...checkMissingAlt(html),
@@ -621,6 +849,7 @@ export default defineAction({
       ...checkFocusVisibility(html),
       ...checkContrastHint(html),
       ...tokenDriftFindings,
+      ...designSystemFindings,
     ];
 
     // Summarise by severity for the agent context.

package/corpus/templates/design/actions/sync-design-system-with-builder.ts

@@ -0,0 +1,64 @@
+import { defineAction } from "@agent-native/core";
+import {
+  parseBuilderDesignSystemProxyReference,
+  startBuilderDesignSystemIndex,
+} from "@agent-native/core/server";
+import { getRequestUserEmail } from "@agent-native/core/server/request-context";
+import { assertAccess, resolveAccess } from "@agent-native/core/sharing";
+import { z } from "zod";
+
+import "../server/db/index.js";
+import { upsertBuilderProxyDesignSystem } from "../server/lib/builder-design-system-proxy.js";
+
+export default defineAction({
+  description:
+    "Re-index a Builder-backed GitHub design system using its persisted repository, ref, and file/folder scope. Requires editor access.",
+  schema: z.object({
+    id: z.string().min(1).describe("Local design system id"),
+  }),
+  run: async ({ id }) => {
+    await assertAccess("design-system", id, "editor");
+    const access = await resolveAccess("design-system", id);
+    if (!access) throw new Error("Design system not found");
+
+    const reference = parseBuilderDesignSystemProxyReference(
+      access.resource.data,
+    );
+    if (!reference?.githubSources?.length) {
+      throw new Error(
+        "This design system has no persisted GitHub source scope to sync.",
+      );
+    }
+    if (reference.sourceKind === "mixed") {
+      throw new Error(
+        "This design system combines GitHub with non-replayable sources. Re-import all sources before syncing it.",
+      );
+    }
+
+    const result = await startBuilderDesignSystemIndex({
+      projectName: access.resource.title,
+      description: access.resource.description ?? undefined,
+      githubRepos: reference.githubSources,
+    });
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("no authenticated user");
+
+    const proxy = await upsertBuilderProxyDesignSystem({
+      result,
+      ownerEmail: access.resource.ownerEmail,
+      orgId: access.resource.orgId,
+      projectName: access.resource.title,
+      description: access.resource.description ?? undefined,
+      sourceKind: reference.sourceKind,
+      githubSources: reference.githubSources,
+      localDesignSystemId: id,
+    });
+
+    return {
+      ...result,
+      ...proxy,
+      synced: true,
+      githubSourceCount: reference.githubSources.length,
+    };
+  },
+});

package/corpus/templates/design/app/components/design/DesignImportPanel.tsx

@@ -1,5 +1,6 @@
 import { useActionMutation } from "@agent-native/core/client/hooks";
 import { useFormatters, useT } from "@agent-native/core/client/i18n";
+import { docsUrl } from "@agent-native/core/shared";
 import { parseFigmaFileKey } from "@shared/figma-url";
 import {
   IconBrandFigma,
@@ -696,7 +697,7 @@ export function DesignImportPanel(p: DesignImportPanelProps) {
               <p className="text-[11px] leading-snug text-muted-foreground">
                 {t("designEditor.import.visualEditGuidance")}{" "}
                 <a
-                  href="/docs/template-design"
+                  href={docsUrl("template-design")}
                   target="_blank"
                   rel="noreferrer"
                   className="font-medium text-foreground underline-offset-2 hover:underline"

package/corpus/templates/design/app/components/design/TweaksPanel.tsx

@@ -1,4 +1,5 @@
 import { useT } from "@agent-native/core/client/i18n";
+import { docsUrl } from "@agent-native/core/shared";
 import { VisualTweakControl } from "@agent-native/toolkit/design-tweaks";
 import type { TweakDefinition } from "@shared/api";
 import {
@@ -80,7 +81,7 @@ export function TweaksPanelContent({
       >
         {t("designEditor.tweaksHelp")}{" "}
         <a
-          href="/docs/template-design#tweaks"
+          href={docsUrl("template-design")}
           target="_blank"
           rel="noreferrer"
           className="font-medium text-foreground/80 underline-offset-2 hover:text-foreground hover:underline"

package/corpus/templates/design/app/components/design/code-workbench/commands.ts

@@ -169,7 +169,7 @@ const MAC_KEY_LABELS: Record<string, string> = {
   escape: "⎋",
 };
 
-/** Human-readable keybinding, e.g. "⇧⌘P" on macOS or "Ctrl+Shift+P". */
+/** Human-readable keybinding, e.g. "⇧⌘P" on macOS or "Ctrl Shift P". */
 export function formatKeybinding(binding: string): string {
   const parsed = parseKeybinding(binding);
   const keyLabel =
@@ -191,7 +191,7 @@ export function formatKeybinding(binding: string): string {
   if (parsed.alt) parts.push("Alt");
   if (parsed.shift) parts.push("Shift");
   parts.push(keyLabel.length === 1 ? keyLabel.toUpperCase() : keyLabel);
-  return parts.join("+");
+  return parts.join(" ");
 }
 
 /**