@agent-native/core 0.80.4 → 0.80.6

package/corpus/templates/content/changelog/2026-06-29-builder-review-checks-now-preserve-publish-and-unpublish-cho.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-06-29
+---
+
+Builder review checks now preserve publish and unpublish choices before sending updates.

package/corpus/templates/content/changelog/2026-06-29-database-sources-can-now-be-added-as-more-rows-or-matched.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-06-29
+---
+
+Database sources can now be added as more rows or matched details, with an in-app role repair path and field picker.

package/corpus/templates/content/changelog/2026-06-29-fixed-loading-the-final-rows-in-larger-databases-without-bre.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-06-29
+---
+
+Fixed loading the final rows in larger databases without breaking the table.

package/corpus/templates/content/changelog/2026-06-29-reusable-mdx-references-now-preview-linked-local-documents-i.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-06-29
+---
+
+Reusable MDX references now preview linked local documents inline.

package/corpus/templates/content/shared/api.ts

@@ -351,6 +351,11 @@ export type ContentDatabaseSourcePushMode =
   | "autosave"
   | "draft"
   | "publish";
+export type ContentDatabaseSourceWriteMode =
+  | "read_only"
+  | "stage_only"
+  | "publish_updates";
+export type BuilderCmsPublicationTransitionIntent = "publish" | "unpublish";
 export const BUILDER_CMS_SAFE_WRITE_MODEL = "agent-native-blog-article-test";
 export type ContentDatabaseSourceChangeDirection = "outbound";
 export type ContentDatabaseSourceChangeState =
@@ -545,6 +550,8 @@ export interface ContentDatabaseSource {
     pushMode?: ContentDatabaseSourcePushMode;
     pushModeLabel?: string | null;
     pushModeDescription?: string | null;
+    writeMode?: ContentDatabaseSourceWriteMode;
+    allowPublicationTransitions?: boolean;
     notes?: string | null;
     readMode?: "fixture" | "builder-api" | string | null;
     liveReadConfigured?: boolean;
@@ -688,6 +695,21 @@ export interface AttachContentDatabaseSourceRequest {
   sourceType?: ContentDatabaseSourceType;
   sourceName?: string;
   sourceTable?: string;
+  /** "items" adds more rows; "details" joins fields onto existing rows. */
+  relationshipMode?: "items" | "details";
+  join?: ContentDatabaseSourceJoinRequest;
+  /** "add" attaches an additional row-union source; "replace" (default) re-links the primary. */
+  mode?: "replace" | "add";
+  limit?: number;
+  offset?: number;
+}
+
+export interface ChangeContentDatabaseSourceRoleRequest {
+  databaseId?: string;
+  documentId?: string;
+  sourceId: string;
+  /** "items" adds more rows; "details" joins fields onto existing rows. */
+  relationshipMode: "items" | "details";
   join?: ContentDatabaseSourceJoinRequest;
   limit?: number;
   offset?: number;
@@ -748,6 +770,7 @@ export interface SuggestSourceJoinKeyResponse {
 export interface RefreshContentDatabaseSourceRequest {
   databaseId?: string;
   documentId?: string;
+  sourceId?: string;
 }
 
 export interface DisconnectContentDatabaseSourceRequest {
@@ -762,14 +785,24 @@ export interface AddContentDatabaseSourceFieldPropertyRequest {
   sourceFieldId: string;
 }
 
+export interface BindContentDatabaseSourceFieldRequest {
+  databaseId?: string;
+  documentId?: string;
+  sourceFieldId: string;
+  // Target column to bind the source field to, or null to unbind.
+  propertyId: string | null;
+}
+
 export interface StageBuilderRevisionRequest {
   databaseId?: string;
   documentId?: string;
+  sourceId?: string;
 }
 
 export interface ReviewContentDatabaseSourceChangeSetRequest {
   databaseId?: string;
   documentId?: string;
+  sourceId?: string;
   changeSetId: string;
   decision: "approve" | "reject";
   note?: string;
@@ -778,29 +811,74 @@ export interface ReviewContentDatabaseSourceChangeSetRequest {
 export interface PrepareBuilderSourceExecutionRequest {
   databaseId?: string;
   documentId?: string;
+  sourceId?: string;
   changeSetId: string;
   pushModeConfirmation?: ContentDatabaseSourcePushMode;
+  publicationTransition?: BuilderCmsPublicationTransitionIntent;
+  confirmUnpublish?: boolean;
 }
 
 export interface ValidateBuilderSourceExecutionRequest {
   databaseId?: string;
   documentId?: string;
+  sourceId?: string;
   changeSetId: string;
   idempotencyKey?: string;
+  pushModeConfirmation?: ContentDatabaseSourcePushMode;
+  publicationTransition?: BuilderCmsPublicationTransitionIntent;
+  confirmUnpublish?: boolean;
 }
 
 export interface ExecuteBuilderSourceExecutionRequest {
   databaseId?: string;
   documentId?: string;
+  sourceId?: string;
   changeSetId: string;
   idempotencyKey?: string;
   pushModeConfirmation?: ContentDatabaseSourcePushMode;
+  publicationTransition?: BuilderCmsPublicationTransitionIntent;
+  confirmUnpublish?: boolean;
+}
+
+export interface ExecuteBuilderSourceBatchTransition {
+  publicationTransition?: BuilderCmsPublicationTransitionIntent;
+  confirmUnpublish?: boolean;
+}
+
+export interface ExecuteBuilderSourceBatchRequest {
+  databaseId?: string;
+  documentId?: string;
+  sourceId?: string;
+  changeSetIds?: string[];
+  maxConcurrency?: number;
+  transitions?: Record<string, ExecuteBuilderSourceBatchTransition>;
+}
+
+export type BuilderSourceBatchItemStatus = "succeeded" | "blocked" | "failed";
+
+export interface BuilderSourceBatchItemResult {
+  changeSetId: string;
+  status: BuilderSourceBatchItemStatus;
+  message?: string;
+}
+
+export interface ExecuteBuilderSourceBatchResponse {
+  summary: {
+    total: number;
+    succeeded: number;
+    blocked: number;
+    failed: number;
+  };
+  results: BuilderSourceBatchItemResult[];
 }
 
 export interface SetContentDatabaseSourceWriteModeRequest {
   databaseId?: string;
   documentId?: string;
-  liveWritesEnabled: boolean;
+  sourceId?: string;
+  liveWritesEnabled?: boolean;
+  writeMode?: ContentDatabaseSourceWriteMode;
+  allowPublicationTransitions?: boolean;
   allowedWriteModes?: Exclude<ContentDatabaseSourcePushMode, "none">[];
   allowDraftWrites?: boolean;
   allowPublishWrites?: boolean;
@@ -809,9 +887,19 @@ export interface SetContentDatabaseSourceWriteModeRequest {
 export interface PrepareBuilderSourceReviewRequest {
   databaseId?: string;
   documentId?: string;
+  sourceId?: string;
   pushModeConfirmation?: ContentDatabaseSourcePushMode;
+  publicationTransition?: BuilderCmsPublicationTransitionIntent;
+  confirmUnpublish?: boolean;
 }
 
+export type BuilderCmsWriteEffect =
+  | "autosave"
+  | "update_in_place"
+  | "create_draft"
+  | "publish"
+  | "unpublish";
+
 export interface ContentDatabaseSourceReviewRowSummary {
   changeSetId: string;
   databaseItemId: string | null;
@@ -822,6 +910,8 @@ export interface ContentDatabaseSourceReviewRowSummary {
   riskLevel: ContentDatabaseSourceRiskLevel;
   riskReasons: string[];
   conflictState: ContentDatabaseSourceConflictState;
+  /** Resolved write effect for this row — drives plain-language UI labels. */
+  effect: BuilderCmsWriteEffect;
   execution: ContentDatabaseSourceExecution | null;
 }
 

package/corpus/templates/content/shared/builder-docs-blocks.ts

@@ -49,6 +49,8 @@ export interface BuilderTabbedContentData extends BuilderRawRefData {
 export interface BuilderSymbolData extends BuilderRawRefData {
   entry?: string;
   model?: string;
+  source?: string;
+  dynamic?: boolean;
   data?: Record<string, unknown>;
 }
 
@@ -104,6 +106,8 @@ export const builderSymbolSchema = z.object({
   ...rawRefSchema,
   entry: z.string().trim().max(240).optional(),
   model: z.string().trim().max(120).optional(),
+  source: z.string().trim().max(2_000).optional(),
+  dynamic: z.boolean().optional(),
   data: z.record(z.string(), z.unknown()).optional(),
 }) as unknown as z.ZodType<BuilderSymbolData>;
 
@@ -203,6 +207,8 @@ export const builderSymbolMdx: BlockMdxConfig<BuilderSymbolData> = {
     ...rawRefAttrs(data),
     entry: data.entry,
     model: data.model,
+    source: data.source,
+    dynamic: data.dynamic,
     data: data.data,
   }),
   fromAttrs: (attrs) => ({
@@ -211,6 +217,8 @@ export const builderSymbolMdx: BlockMdxConfig<BuilderSymbolData> = {
     componentName: attrs.string("componentName"),
     entry: attrs.string("entry"),
     model: attrs.string("model"),
+    source: attrs.string("source"),
+    dynamic: attrs.bool("dynamic"),
     data: attrs.object<Record<string, unknown>>("data"),
   }),
 };

package/corpus/templates/content/shared/builder-mdx.ts

@@ -20,6 +20,7 @@ export const BUILDER_DOCS_MODELS = [
   "docs-content",
   "blog-article",
   "agent-native-blog-article-test",
+  "symbol",
 ] as const;
 
 export type BuilderDocsModel = (typeof BUILDER_DOCS_MODELS)[number] | string;
@@ -175,6 +176,7 @@ export function builderRawRootForEntry(model: string, entryId: string) {
 function modelDirectory(model: string) {
   if (model === "docs-content") return "docs";
   if (model === "blog-article") return "blog";
+  if (model === "symbol") return "symbols";
   return safePathPart(model);
 }
 
@@ -194,6 +196,23 @@ export function builderMdxPathForEntry(entry: BuilderContentEntry) {
   )}/${slug}${BUILDER_DOCS_MDX_EXTENSION}`;
 }
 
+function builderSymbolMdxPathForEntry(entry: BuilderContentEntry) {
+  const data = entry.data ?? {};
+  const title = builderEntryTitle(entry);
+  const handle = stringFromRecord(data, [
+    "handle",
+    "slug",
+    "urlPath",
+    "url",
+    "path",
+  ]);
+  const slug = slugify(handle?.replace(/^\/+|\/+$/g, "") || title, entry.id);
+  return `${BUILDER_DOCS_CONTENT_ROOT}/symbols/${safePathPart(
+    entry.model,
+    "symbol",
+  )}/${slug}${BUILDER_DOCS_MDX_EXTENSION}`;
+}
+
 function stringFromRecord(
   record: Record<string, unknown>,
   keys: string[],
@@ -357,6 +376,50 @@ function childBlocks(block: unknown): unknown[] {
   return Array.isArray(block.children) ? block.children : [];
 }
 
+function symbolContentEntry(
+  symbol: Record<string, unknown>,
+): BuilderContentEntry | null {
+  const content = isRecord(symbol.content) ? symbol.content : null;
+  if (!content) return null;
+  const rawModel = stringFromRecord(symbol, ["model"]);
+  const rawEntry = stringFromRecord(symbol, ["entry"]);
+  const id = stringFromRecord(content, ["id", "entry", "uid"]) ?? rawEntry;
+  if (!id) return null;
+
+  const model =
+    stringFromRecord(content, ["model", "modelName", "queryModel"]) ??
+    rawModel ??
+    "symbol";
+  const data = isRecord(content.data)
+    ? (JSON.parse(JSON.stringify(content.data)) as Record<string, unknown>)
+    : {};
+  if (!Array.isArray(data.blocks) && Array.isArray(content.blocks)) {
+    data.blocks = content.blocks;
+  }
+  if (!data.blocks) return null;
+
+  return {
+    ...content,
+    id,
+    model,
+    name:
+      stringFromRecord(content, ["name"]) ??
+      stringFromRecord(data, ["title", "pageTitle", "name"]) ??
+      id,
+    published:
+      typeof content.published === "string" ? content.published : undefined,
+    lastUpdated:
+      typeof content.lastUpdated === "string" ||
+      typeof content.lastUpdated === "number"
+        ? content.lastUpdated
+        : typeof content.updatedDate === "string" ||
+            typeof content.updatedDate === "number"
+          ? content.updatedDate
+          : undefined,
+    data,
+  };
+}
+
 function blockSummary(block: unknown) {
   const name = componentName(block);
   const options = componentOptions(block);
@@ -382,6 +445,7 @@ interface BlocksToMdxContext {
   rawRoot: string;
   files: Record<string, string>;
   warnings: string[];
+  emitReferencedEntry: (entry: BuilderContentEntry) => Promise<string>;
 }
 
 async function builderBlocksToMdxBody(
@@ -493,10 +557,19 @@ async function builderBlockToMdx(
 
   if (name === "Symbol") {
     const symbol = isRecord(options.symbol) ? options.symbol : {};
+    const contentEntry = symbolContentEntry(symbol);
+    const source = contentEntry
+      ? await ctx.emitReferencedEntry(contentEntry)
+      : undefined;
     const data: BuilderSymbolData = {
       ...raw,
       entry: typeof symbol.entry === "string" ? symbol.entry : undefined,
       model: typeof symbol.model === "string" ? symbol.model : undefined,
+      source,
+      dynamic:
+        boolFromRecord(symbol, "dynamic") ??
+        boolFromRecord(symbol, "isDynamic") ??
+        boolFromRecord(options, "dynamicSymbol"),
       data: isRecord(symbol.data) ? symbol.data : undefined,
     };
     return serializeRegistryBlockToMdx("builder-symbol", {
@@ -525,12 +598,76 @@ async function builderBlockToMdx(
 export async function builderEntryToMdxBundle(
   entry: BuilderContentEntry,
 ): Promise<BuilderMdxBundle> {
+  const files: Record<string, string> = {};
+  const warnings: string[] = [];
+  const emitted = new Set<string>();
+  const mdx = await emitBuilderEntryToMdxFile({
+    entry,
+    files,
+    warnings,
+    emitted,
+    symbolPath: false,
+  });
+  return { mdx, files, blocks: builderEntryBlocks(entry) };
+}
+
+async function emitBuilderEntryToMdxFile({
+  entry,
+  files,
+  warnings,
+  emitted,
+  symbolPath,
+}: {
+  entry: BuilderContentEntry;
+  files: Record<string, string>;
+  warnings: string[];
+  emitted: Set<string>;
+  symbolPath: boolean;
+}): Promise<BuilderMdxFile> {
+  const path = symbolPath
+    ? builderSymbolMdxPathForEntry(entry)
+    : builderMdxPathForEntry(entry);
+  const key = `${entry.model}:${entry.id}:${path}`;
+  if (emitted.has(key)) {
+    return {
+      path,
+      documentId: builderDocumentId(entry.model, entry.id),
+      title: builderEntryTitle(entry),
+      metadata: {
+        model: entry.model,
+        entryId: entry.id,
+        lastUpdated: normalizeRemoteUpdatedAt(entry),
+        published: entry.published,
+        sourceHash: builderSourceHash(entry),
+        blocksHash: builderBlocksHash(builderEntryBlocks(entry)),
+        rawRoot: builderRawRootForEntry(entry.model, entry.id),
+        path,
+      },
+      frontmatter: {},
+      body: "",
+      source: files[path] ?? "",
+    };
+  }
+  emitted.add(key);
+
   const blocks = builderEntryBlocks(entry);
   const rawRoot = builderRawRootForEntry(entry.model, entry.id);
-  const files: Record<string, string> = {};
-  const ctx: BlocksToMdxContext = { rawRoot, files, warnings: [] };
+  const ctx: BlocksToMdxContext = {
+    rawRoot,
+    files,
+    warnings,
+    emitReferencedEntry: async (referencedEntry) => {
+      const nested = await emitBuilderEntryToMdxFile({
+        entry: referencedEntry,
+        files,
+        warnings,
+        emitted,
+        symbolPath: true,
+      });
+      return nested.path;
+    },
+  };
   const body = await builderBlocksToMdxBody(blocks, ctx);
-  const path = builderMdxPathForEntry(entry);
   const blocksHash = builderBlocksHash(blocks);
   const sourceHash = builderSourceHash(entry);
   const frontmatter = frontmatterForEntry({
@@ -552,7 +689,7 @@ export async function builderEntryToMdxBundle(
     source,
   };
   files[path] = source;
-  return { mdx, files, blocks };
+  return mdx;
 }
 
 function parseFrontmatterValue(value: string): unknown {

package/corpus/templates/content/shared/nfm.ts

@@ -673,6 +673,7 @@ function serializeBlock(node: PMNode, indent: number): string[] {
       return serializeBlockAtom(node, ind);
     case "registryBlock":
       return serializeRegistryBlock(node, ind);
+    case "contentReference":
     case "localMdxComponent":
       return serializeRawSourceBlock(node, ind);
     default: {
@@ -1199,6 +1200,19 @@ function parseSingleBlock(
     return { nodes: [withIndentAttr(node)], end: childRes.end };
   }
 
+  // Content reference (Notion-style reusable MDX transclusion). The source
+  // owns the reference; the editor resolves and previews it from local files.
+  const contentReferenceTag = matchContentReferenceOpen(dedent);
+  if (contentReferenceTag) {
+    return parseContentReference(
+      lines,
+      start,
+      indent,
+      rel,
+      contentReferenceTag,
+    );
+  }
+
   // Registry block (PascalCase MDX element: <Endpoint .../>, <Checklist .../>,
   // <DataModel …>…</DataModel>, …). These are the dev-doc / OpenAPI library
   // blocks shared with plan, encoded inline. They are recognized by the content
@@ -1288,6 +1302,12 @@ function matchRegistryBlockOpen(dedent: string): string | null {
   return registryBlockSpecByTag(tag) ? tag : null;
 }
 
+function matchContentReferenceOpen(dedent: string): string | null {
+  return /^<ContentReference(?:[\s/>]|$)/.test(dedent)
+    ? "ContentReference"
+    : null;
+}
+
 function matchLocalMdxComponentOpen(dedent: string): string | null {
   const m = dedent.match(/^<([A-Z][\w-]*)(?:[\s/>]|$)/);
   if (!m) return null;
@@ -1424,6 +1444,48 @@ function parseRegistryBlock(
   return { nodes: [withIndentAttr(node)], end };
 }
 
+function parseContentReference(
+  lines: string[],
+  start: number,
+  indent: number,
+  rel: number,
+  _tag: string,
+): ParseResult {
+  const withIndentAttr = (node: PMNode): PMNode => {
+    if (rel > 0) node.attrs = { ...(node.attrs || {}), indent: rel };
+    return node;
+  };
+  const dedented = lines.map((l) => stripTabs(l, indent));
+
+  let openEndLine = start;
+  {
+    let joined = "";
+    for (let i = start; i < lines.length; i++) {
+      joined += (i === start ? "" : "\n") + dedented[i];
+      const res = scanOpenTagEnd(joined);
+      if (res) {
+        openEndLine = i;
+        break;
+      }
+      openEndLine = i;
+    }
+  }
+
+  const rawLines = dedented.slice(start, openEndLine + 1);
+  const raw = rawLines.join("\n");
+  const props = parseAttrs(raw);
+  const node: PMNode = {
+    type: "contentReference",
+    attrs: {
+      sourcePath:
+        props.sourcePath ?? props.path ?? props.source ?? props.href ?? "",
+      title: props.title ?? null,
+      __raw: raw,
+    },
+  };
+  return { nodes: [withIndentAttr(node)], end: openEndLine + 1 };
+}
+
 function parseLocalMdxComponent(
   lines: string[],
   start: number,

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

@@ -31,6 +31,15 @@ const LOCAL_COMPONENTS_STUB_IMPORTS = new Set([
   "./local-components.generated.ts",
 ]);
 const COMPONENT_EXTENSIONS = new Set([".tsx", ".jsx", ".ts", ".js"]);
+const LOCAL_COMPONENT_SKIP_DIRS = new Set([
+  "__tests__",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+]);
+const LOCAL_COMPONENT_SKIP_FILE_RE =
+  /(?:^|[.-])(?:test|spec|stories|story)\.[cm]?[jt]sx?$/;
 const ALLOW_PRODUCTION_LOCAL_FILES_ENV =
   "AGENT_NATIVE_ALLOW_LOCAL_FILES_IN_PRODUCTION";
 const CONTENT_LOCAL_DEFAULTS: LocalArtifactOptions["defaults"] = {
@@ -145,18 +154,16 @@ async function walkComponentFiles(directory: string): Promise<string[]> {
     if (entry.isSymbolicLink()) continue;
     const absolutePath = path.join(directory, entry.name);
     if (entry.isDirectory()) {
-      if (
-        entry.name === "node_modules" ||
-        entry.name === "dist" ||
-        entry.name === "build"
-      ) {
-        continue;
-      }
+      if (LOCAL_COMPONENT_SKIP_DIRS.has(entry.name)) continue;
       files.push(...(await walkComponentFiles(absolutePath)));
       continue;
     }
     if (
       !entry.isFile() ||
+      entry.name.endsWith(".generated.ts") ||
+      entry.name.endsWith(".generated.tsx") ||
+      entry.name.endsWith(".d.ts") ||
+      LOCAL_COMPONENT_SKIP_FILE_RE.test(entry.name) ||
       !COMPONENT_EXTENSIONS.has(path.extname(entry.name).toLowerCase())
     ) {
       continue;

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

@@ -178,19 +178,18 @@ Extracts CSS tokens from a project's generated HTML, or clones an existing desig
 ### Source: Figma file
 
 ```bash
-pnpm action import-figma --figmaUrl "https://figma.com/design/<key>/..." \
-  --description "<extracted tokens / styles summary>"
+pnpm action index-design-system-with-builder \
+  --projectName "Acme Figma system" \
+  --codeFiles '[{"filename":"figma-summary.md","content":"<extracted tokens / styles summary>"}]'
 ```
 
-**Prefer the connected Figma MCP** when available (tools like
-`get_variable_defs`, `get_design_context`, `get_metadata`, `get_screenshot`).
-Call those on the file/selection FIRST to pull real variables (tokens), color
-and text styles, and a screenshot — this sidesteps REST/Enterprise limits and
-returns a token map directly. Then pass that summary to `import-figma` and build
-the system with `create-design-system`. Convert Figma colors (0-1 RGBA) to hex,
-effects to CSS box-shadow, and text styles to font tokens; snap spacing to a
-4/8px scale. If no Figma MCP is connected, ask the user to paste the token
-values or describe the file.
+Builder is the required extraction/indexing path for Figma-backed design
+systems. If a connected Figma MCP is available (tools like `get_variable_defs`,
+`get_design_context`, `get_metadata`, `get_screenshot`), call those on the
+file/selection first to pull real variables, color/text styles, and screenshot
+notes, then pass that summary to `index-design-system-with-builder` as an
+uploaded text context file. Do not build a local design system from the Figma
+summary unless the user explicitly asks for a manual local fallback.
 
 **When the user uploads a raw `.fig` file**, send it to Builder design-system
 indexing through the setup page upload route. Do not parse `.fig` files locally

package/corpus/templates/design/AGENTS.md

@@ -101,6 +101,11 @@ patterns live in `.agents/skills/`.
   progress. External MCP hosts should use `present-design-variants` so the same
   picker opens inline instead of writing `application_state` directly.
 - Use framework sharing actions for design and design-system visibility/grants.
+- `/visual-edit` is a public entry route and public `/design/:id` links may
+  render read-only public designs without a session. Do not open anonymous write
+  actions: save, share, generation, localhost connection, and screen persistence
+  should send signed-out visitors through `/_agent-native/sign-in?return=...`,
+  then save or copy the design into the authenticated account before sharing.
 - When the user asks to download/export, use export actions or point to the
   editor download menu.
 - Design source modes are `inline`, `localhost`, and `fusion`. Inline is the

package/corpus/templates/design/_gitignore

@@ -37,3 +37,10 @@ data/.sessions.json
 learnings.md
 
 .vercel/
+
+# Playwright E2E
+/test-results/
+/playwright-report/
+/e2e/.auth/
+data/e2e.db
+data/e2e.db-*

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

@@ -32,18 +32,28 @@ function parseJsonString(value: unknown): unknown {
 
 const sourceSchema = z.preprocess(
   parseJsonString,
-  z.object({
-    kind: z
-      .enum(["design-file", "inline-html", "local-file", "remote-url"])
-      .default("design-file"),
-    designId: z.string().optional(),
-    fileId: z.string().optional(),
-    filename: z.string().optional().default("index.html"),
-    path: z.string().optional(),
-    url: z.string().optional(),
-    revision: z.string().optional(),
-    html: z.string().optional(),
-  }),
+  z
+    .object({
+      kind: z
+        .enum(["design-file", "inline-html", "local-file", "remote-url"])
+        .default("design-file"),
+      designId: z.string().optional(),
+      fileId: z.string().optional(),
+      filename: z.string().optional().default("index.html"),
+      path: z.string().optional(),
+      url: z.string().optional(),
+      revision: z.string().optional(),
+      html: z.string().optional(),
+    })
+    .superRefine((source, ctx) => {
+      if (source.kind === "design-file" && !source.designId && !source.fileId) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["designId"],
+          message: "designId or fileId is required for design-file sources",
+        });
+      }
+    }),
 );
 
 const targetSchema = z.object({