@builder.io/ai-utils 0.106.0 → 0.108.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.106.0",
+  "version": "0.108.0",
   "description": "Builder.io AI utils",
   "files": [
     "src"

package/src/codegen.d.ts

@@ -125,12 +125,22 @@ export declare const ReadToolInputSchema: z.ZodObject<{
     limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
 export type ReadToolInput = z.infer<typeof ReadToolInputSchema>;
+/** Image files the Read tool returns as image content instead of rejecting as binary. */
+declare const READ_TOOL_IMAGE_MEDIA_TYPES: {
+    readonly ".png": "image/png";
+    readonly ".jpg": "image/jpeg";
+    readonly ".jpeg": "image/jpeg";
+    readonly ".gif": "image/gif";
+    readonly ".webp": "image/webp";
+};
+export declare function readToolImageMediaType(filePath: string): (typeof READ_TOOL_IMAGE_MEDIA_TYPES)[keyof typeof READ_TOOL_IMAGE_MEDIA_TYPES] | undefined;
 export declare const GlobSearchToolInputSchema: z.ZodObject<{
     pattern: z.ZodString;
 }, z.core.$strip>;
 export type GlobSearchToolInput = z.infer<typeof GlobSearchToolInputSchema>;
 export declare const GrepSearchToolInputSchema: z.ZodObject<{
     query: z.ZodString;
+    node_modules_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     include_glob: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     exclude_glob: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     case_sensitive: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
@@ -1506,6 +1516,7 @@ export declare const CodeGenToolMapSchema: z.ZodObject<{
     }, z.core.$strip>;
     Grep: z.ZodObject<{
         query: z.ZodString;
+        node_modules_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         include_glob: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         exclude_glob: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         case_sensitive: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
@@ -4497,6 +4508,8 @@ export interface FusionConfig {
     branchFriendlyName?: string;
     sessionId?: string;
     browserAutomationInstructions?: string;
+    /** Start a headed Chromium in the container, driven from scripts over DevTools. */
+    branchBrowser?: boolean;
     /** Whether this branch is for a code review - affects enabled agents and tools */
     branchType?: BranchType;
     /**

package/src/codegen.js

@@ -128,9 +128,24 @@ export const ReadToolInputSchema = z
     }),
 })
     .meta({ title: "ReadToolInput" });
+/** Image files the Read tool returns as image content instead of rejecting as binary. */
+const READ_TOOL_IMAGE_MEDIA_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
+export function readToolImageMediaType(filePath) {
+    const lower = filePath.toLowerCase();
+    const ext = lower.slice(lower.lastIndexOf("."));
+    return READ_TOOL_IMAGE_MEDIA_TYPES[ext];
+}
 export const GlobSearchToolInputSchema = z
     .object({
-    pattern: z.string().meta({ description: "The pattern to search for" }),
+    pattern: z.string().meta({
+        description: "The pattern to search for. node_modules and dist folders are skipped unless the pattern starts with a path inside node_modules (e.g. 'node_modules/@tabler/icons-react/**/*.d.ts').",
+    }),
 })
     .meta({ title: "GlobSearchToolInput" });
 export const GrepSearchToolInputSchema = z
@@ -138,6 +153,9 @@ export const GrepSearchToolInputSchema = z
     query: z.string().meta({
         description: 'A string literal or a JavaScript-flavored regex to search for in all project files. Only escape special characters such as {} and () in string literals to avoid confusion with regex patterns (e.g. "import \\{ foo \\}"). Avoid over-escaping as that will cause errors. Do NOT use inline regex flags like (?i) or (?s) — they are not supported. The search is case-insensitive by default; use the case_sensitive parameter to control this.',
     }),
+    node_modules_path: z.string().nullish().meta({
+        description: "Searches an installed package instead of the project. node_modules and dist folders are skipped by default; set this to a directory or file inside node_modules (e.g. 'node_modules/@tabler/icons-react') to search that package, including its dist folder and .d.ts files.",
+    }),
     include_glob: z.string().nullish().meta({
         description: "An optional single glob pattern to include only specific files (e.g. '**/*.(ts|tsx)' for all TypeScript files)",
     }),

package/src/common-schemas.d.ts

@@ -7,6 +7,11 @@ export declare const EnvironmentVariableSchema: z.ZodObject<{
     explanation: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type EnvironmentVariable = z.infer<typeof EnvironmentVariableSchema>;
+export declare const NETLIFY_PRODUCTION_ENV_VALUE_MAX_LENGTH = 5000;
+export declare function getOversizedProductionEnvVar(entries: ReadonlyArray<EnvironmentVariable> | undefined): {
+    key: string;
+    length: number;
+} | undefined;
 export declare const SetupMiseDependencySchema: z.ZodObject<{
     key: z.ZodString;
     type: z.ZodLiteral<"mise">;

package/src/common-schemas.js

@@ -19,6 +19,18 @@ export const EnvironmentVariableSchema = z
     }),
 })
     .meta({ title: "EnvironmentVariable" });
+export const NETLIFY_PRODUCTION_ENV_VALUE_MAX_LENGTH = 5000;
+export function getOversizedProductionEnvVar(entries) {
+    for (const entry of entries !== null && entries !== void 0 ? entries : []) {
+        const key = entry.key.trim();
+        if (key &&
+            !entry.placeholder &&
+            entry.value.length > NETLIFY_PRODUCTION_ENV_VALUE_MAX_LENGTH) {
+            return { key, length: entry.value.length };
+        }
+    }
+    return undefined;
+}
 export const SetupMiseDependencySchema = z
     .object({
     key: z.string(),

package/src/credits.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export declare const BuilderReferralInfoResponseSchema: z.ZodObject<{
+    eligible: z.ZodBoolean;
+    inviteUrl: z.ZodNullable<z.ZodURL>;
+    creditsPerReferral: z.ZodNumber;
+    completedReferrals: z.ZodNumber;
+    pendingReferrals: z.ZodNumber;
+    creditsEarned: z.ZodNumber;
+}, z.core.$strip>;
+export type BuilderReferralInfoResponse = z.infer<typeof BuilderReferralInfoResponseSchema>;

package/src/credits.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+export const BuilderReferralInfoResponseSchema = z.object({
+    eligible: z.boolean(),
+    inviteUrl: z.url().nullable(),
+    creditsPerReferral: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    completedReferrals: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    pendingReferrals: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    creditsEarned: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+});

package/src/index.d.ts

@@ -22,6 +22,7 @@ export * from "./single-tenancy.js";
 export * from "./design-systems.js";
 export * from "./editor-ai.js";
 export * from "./realtime.js";
+export * from "./credits.js";
 export * from "./embeddings.js";
 export * from "./system-one.js";
 export * from "./mcp-servers.js";

package/src/index.js

@@ -22,6 +22,7 @@ export * from "./single-tenancy.js";
 export * from "./design-systems.js";
 export * from "./editor-ai.js";
 export * from "./realtime.js";
+export * from "./credits.js";
 export * from "./embeddings.js";
 export * from "./system-one.js";
 export * from "./mcp-servers.js";

package/src/organization.d.ts

@@ -355,6 +355,7 @@ export interface FeatureMap {
     performanceInfrastructure?: boolean;
     previewPasswordProtection?: boolean;
     siteAccessControl?: boolean;
+    hostingCustomDomain?: boolean;
     publicPreviews?: boolean;
     privacyMode?: boolean;
     usageInsights?: boolean;

package/src/projects.d.ts

@@ -472,7 +472,13 @@ export declare const ProjectSkillSchema: z.ZodUnion<readonly [z.ZodObject<{
     url: z.ZodString;
 }, z.core.$strip>]>;
 export type ProjectSkill = z.infer<typeof ProjectSkillSchema>;
-export type FusionExecutionEnvironment = "containerized" | "container-less" | "cloud" | "cloud-v2";
+export declare const FusionExecutionEnvironmentSchema: z.ZodEnum<{
+    cloud: "cloud";
+    "cloud-v2": "cloud-v2";
+    "container-less": "container-less";
+    containerized: "containerized";
+}>;
+export type FusionExecutionEnvironment = z.infer<typeof FusionExecutionEnvironmentSchema>;
 export type AgentType = "setup-project" | "project-configuration" | "org-agent" | "code-review-orchestrator" | "design-system-indexer" | "repo-indexer" | "builder-publish-integration";
 export interface PartialBranchData {
     name?: string;
@@ -725,6 +731,19 @@ export interface NewBranch extends BranchSharedData, RequiredBranchSharedData {
  */
 export type Branch = NewBranch | LegacyBranch;
 export declare const checkIsNewBranch: (branch: Branch) => branch is NewBranch;
+/** Identifies a single branch by its project and branch name. */
+export declare const BranchIdentifierSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    branchName: z.ZodString;
+}, z.core.$strip>;
+export type BranchIdentifier = z.infer<typeof BranchIdentifierSchema>;
+/** Query params for `DELETE /projects/branches`. */
+export declare const DeleteBranchOptionsSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    branchName: z.ZodString;
+    hard: z.ZodDefault<z.ZodCodec<z.ZodString, z.ZodBoolean>>;
+}, z.core.$strip>;
+export type DeleteBranchOptions = z.input<typeof DeleteBranchOptionsSchema>;
 /**
  * Request options for `GET /projects/branches/list`. Owner/org scope comes from
  * the authenticated request context; `ownerId` here is a superuser-only override.
@@ -829,6 +848,11 @@ export declare const ShapeOptionSchema: z.ZodObject<{
             designSystemName: z.ZodString;
         }, z.core.$strip>], "kind">>>;
     }, z.core.$strip>>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        delegate: "delegate";
+        "figma-link": "figma-link";
+        upload: "upload";
+    }>>;
 }, z.core.$strip>;
 export type ShapeOption = z.infer<typeof ShapeOptionSchema>;
 export declare const ShapeQuestionSchema: z.ZodObject<{
@@ -853,14 +877,32 @@ export declare const ShapeQuestionSchema: z.ZodObject<{
                 designSystemName: z.ZodString;
             }, z.core.$strip>], "kind">>>;
         }, z.core.$strip>>;
+        kind: z.ZodOptional<z.ZodEnum<{
+            delegate: "delegate";
+            "figma-link": "figma-link";
+            upload: "upload";
+        }>>;
     }, z.core.$strip>>;
     guessOptionId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ShapeQuestion = z.infer<typeof ShapeQuestionSchema>;
+/**
+ * The link in canonical form, or undefined when it is not an https link to a
+ * file on figma.com. Deliberately strict: the result is written into the
+ * user's repo and handed to the agent as a requirement.
+ */
+export declare function parseFigmaFileUrl(value: string): string | undefined;
+/**
+ * The first Figma file link in `text`, canonicalized by `parseFigmaFileUrl`.
+ * Bare and `http:` mentions count as https; trailing punctuation is dropped.
+ */
+export declare function findFigmaFileUrl(text: string): string | undefined;
+export declare function mentionsFigmaFileUrl(text: string): boolean;
 export declare const ShapeAnswerSchema: z.ZodObject<{
     questionId: z.ZodString;
     optionId: z.ZodOptional<z.ZodString>;
     designSystemId: z.ZodOptional<z.ZodString>;
+    figmaUrl: z.ZodOptional<z.ZodString>;
     designSystemName: z.ZodOptional<z.ZodString>;
     skipped: z.ZodBoolean;
     delegated: z.ZodBoolean;
@@ -878,6 +920,7 @@ export declare const ShapeAnswerInputSchema: z.ZodObject<{
     questionId: z.ZodString;
     optionId: z.ZodOptional<z.ZodString>;
     designSystemId: z.ZodOptional<z.ZodString>;
+    figmaUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ShapeAnswerInput = z.infer<typeof ShapeAnswerInputSchema>;
 export declare const GetShapeQuestionnaireOptionsSchema: z.ZodObject<{
@@ -893,6 +936,7 @@ export declare const SubmitShapeAnswersOptionsSchema: z.ZodObject<{
         questionId: z.ZodString;
         optionId: z.ZodOptional<z.ZodString>;
         designSystemId: z.ZodOptional<z.ZodString>;
+        figmaUrl: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type SubmitShapeAnswersOptions = z.infer<typeof SubmitShapeAnswersOptionsSchema>;
@@ -968,6 +1012,11 @@ export declare const ShapeSessionSchema: z.ZodObject<{
                     designSystemName: z.ZodString;
                 }, z.core.$strip>], "kind">>>;
             }, z.core.$strip>>;
+            kind: z.ZodOptional<z.ZodEnum<{
+                delegate: "delegate";
+                "figma-link": "figma-link";
+                upload: "upload";
+            }>>;
         }, z.core.$strip>>;
         guessOptionId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
@@ -976,6 +1025,7 @@ export declare const ShapeSessionSchema: z.ZodObject<{
         questionId: z.ZodString;
         optionId: z.ZodOptional<z.ZodString>;
         designSystemId: z.ZodOptional<z.ZodString>;
+        figmaUrl: z.ZodOptional<z.ZodString>;
         designSystemName: z.ZodOptional<z.ZodString>;
         skipped: z.ZodBoolean;
         delegated: z.ZodBoolean;
@@ -1041,6 +1091,11 @@ export declare const ShapeSessionDocSchema: z.ZodObject<{
                     designSystemName: z.ZodString;
                 }, z.core.$strip>], "kind">>>;
             }, z.core.$strip>>;
+            kind: z.ZodOptional<z.ZodEnum<{
+                delegate: "delegate";
+                "figma-link": "figma-link";
+                upload: "upload";
+            }>>;
         }, z.core.$strip>>;
         guessOptionId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
@@ -1049,6 +1104,7 @@ export declare const ShapeSessionDocSchema: z.ZodObject<{
         questionId: z.ZodString;
         optionId: z.ZodOptional<z.ZodString>;
         designSystemId: z.ZodOptional<z.ZodString>;
+        figmaUrl: z.ZodOptional<z.ZodString>;
         designSystemName: z.ZodOptional<z.ZodString>;
         skipped: z.ZodBoolean;
         delegated: z.ZodBoolean;
@@ -1434,6 +1490,7 @@ export declare const ProjectSettingsSchema: z.ZodObject<{
         instructions: z.ZodOptional<z.ZodString>;
         authUser: z.ZodOptional<z.ZodString>;
         authPassword: z.ZodOptional<z.ZodString>;
+        branchBrowser: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     prReviewer: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodBoolean;
@@ -1771,6 +1828,7 @@ export declare const ProjectSettingsExternalSchema: z.ZodObject<{
         instructions: z.ZodOptional<z.ZodString>;
         authUser: z.ZodOptional<z.ZodString>;
         authPassword: z.ZodOptional<z.ZodString>;
+        branchBrowser: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     prReviewer: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodBoolean;
@@ -2982,6 +3040,7 @@ export declare const UpdateProjectOptionsSchema: z.ZodObject<{
             instructions: z.ZodOptional<z.ZodString>;
             authUser: z.ZodOptional<z.ZodString>;
             authPassword: z.ZodOptional<z.ZodString>;
+            branchBrowser: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>>;
         prReviewer: z.ZodOptional<z.ZodOptional<z.ZodObject<{
             enabled: z.ZodBoolean;
@@ -3692,6 +3751,8 @@ export declare const HostingDomainSchema: z.ZodObject<{
     routeError: z.ZodOptional<z.ZodString>;
     routeErrorAt: z.ZodOptional<z.ZodNumber>;
     servingConfirmedAt: z.ZodOptional<z.ZodNumber>;
+    certIssue: z.ZodOptional<z.ZodString>;
+    certIssueAt: z.ZodOptional<z.ZodNumber>;
     createdBy: z.ZodString;
 }, z.core.$strip>;
 export type HostingDomain = z.infer<typeof HostingDomainSchema>;
@@ -3931,6 +3992,24 @@ export declare const EnsureMainBranchExistsOptionsSchema: z.ZodObject<{
     branchName: z.ZodString;
 }, z.core.$strip>;
 export type EnsureMainBranchExistsOptions = z.infer<typeof EnsureMainBranchExistsOptionsSchema>;
+/** Request body for `POST /projects/ensure-fusion-config`. */
+export declare const EnsureFusionConfigParamsSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    branchName: z.ZodString;
+    includeBackupMetadata: z.ZodOptional<z.ZodBoolean>;
+    volumeMountPath: z.ZodOptional<z.ZodString>;
+    isLocal: z.ZodOptional<z.ZodBoolean>;
+    nativeApp: z.ZodOptional<z.ZodBoolean>;
+    miseLocationPath: z.ZodOptional<z.ZodString>;
+    _useNI: z.ZodOptional<z.ZodBoolean>;
+    fusionEnvironment: z.ZodOptional<z.ZodEnum<{
+        cloud: "cloud";
+        "cloud-v2": "cloud-v2";
+        "container-less": "container-less";
+        containerized: "containerized";
+    }>>;
+}, z.core.$strip>;
+export type EnsureFusionConfigParams = z.infer<typeof EnsureFusionConfigParamsSchema>;
 /**
  * `settings.environmentVariables` is stored with **plaintext** secret values;
  * secrets are masked before this shape leaves ai-services, same as
@@ -4274,6 +4353,7 @@ export declare const ProjectTemplateSchema: z.ZodObject<{
             instructions: z.ZodOptional<z.ZodString>;
             authUser: z.ZodOptional<z.ZodString>;
             authPassword: z.ZodOptional<z.ZodString>;
+            branchBrowser: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>>;
         prReviewer: z.ZodOptional<z.ZodOptional<z.ZodObject<{
             enabled: z.ZodBoolean;
@@ -4699,6 +4779,7 @@ export declare const ProjectTemplateOverridesSchema: z.ZodObject<{
             instructions: z.ZodOptional<z.ZodString>;
             authUser: z.ZodOptional<z.ZodString>;
             authPassword: z.ZodOptional<z.ZodString>;
+            branchBrowser: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>>;
         prReviewer: z.ZodOptional<z.ZodOptional<z.ZodObject<{
             enabled: z.ZodBoolean;
@@ -5092,6 +5173,7 @@ export declare const CreateProjectTemplateFromProjectOptionsSchema: z.ZodPipe<z.
                 instructions: z.ZodOptional<z.ZodString>;
                 authUser: z.ZodOptional<z.ZodString>;
                 authPassword: z.ZodOptional<z.ZodString>;
+                branchBrowser: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>>>;
             prReviewer: z.ZodOptional<z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodBoolean;
@@ -5468,6 +5550,7 @@ export declare const CreateProjectTemplateFromProjectOptionsSchema: z.ZodPipe<z.
                 instructions: z.ZodOptional<z.ZodString>;
                 authUser: z.ZodOptional<z.ZodString>;
                 authPassword: z.ZodOptional<z.ZodString>;
+                branchBrowser: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>>>;
             prReviewer: z.ZodOptional<z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodBoolean;
@@ -5740,6 +5823,7 @@ export declare const CreateProjectTemplateFromProjectOptionsSchema: z.ZodPipe<z.
                 instructions?: string | undefined;
                 authUser?: string | undefined;
                 authPassword?: string | undefined;
+                branchBrowser?: boolean | undefined;
             } | undefined;
             prReviewer?: {
                 enabled: boolean;
@@ -6008,6 +6092,7 @@ export declare const CreateProjectTemplateFromProjectOptionsSchema: z.ZodPipe<z.
                 instructions?: string | undefined;
                 authUser?: string | undefined;
                 authPassword?: string | undefined;
+                branchBrowser?: boolean | undefined;
             } | undefined;
             prReviewer?: {
                 enabled: boolean;
@@ -6270,6 +6355,7 @@ export declare const CreateProjectTemplateFromProjectOptionsSchema: z.ZodPipe<z.
                 instructions?: string | undefined;
                 authUser?: string | undefined;
                 authPassword?: string | undefined;
+                branchBrowser?: boolean | undefined;
             } | undefined;
             prReviewer?: {
                 enabled: boolean;
@@ -6693,6 +6779,7 @@ export declare const ListProjectTemplatesResponseSchema: z.ZodObject<{
                 instructions: z.ZodOptional<z.ZodString>;
                 authUser: z.ZodOptional<z.ZodString>;
                 authPassword: z.ZodOptional<z.ZodString>;
+                branchBrowser: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>>>;
             prReviewer: z.ZodOptional<z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodBoolean;
@@ -7113,6 +7200,7 @@ export declare const UpdateProjectTemplateOptionsSchema: z.ZodObject<{
                 instructions: z.ZodOptional<z.ZodString>;
                 authUser: z.ZodOptional<z.ZodString>;
                 authPassword: z.ZodOptional<z.ZodString>;
+                branchBrowser: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>>>;
             prReviewer: z.ZodOptional<z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodBoolean;
@@ -7525,6 +7613,7 @@ export declare const UpdateProjectTemplateResponseSchema: z.ZodObject<{
                 instructions: z.ZodOptional<z.ZodString>;
                 authUser: z.ZodOptional<z.ZodString>;
                 authPassword: z.ZodOptional<z.ZodString>;
+                branchBrowser: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>>>;
             prReviewer: z.ZodOptional<z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodBoolean;

package/src/projects.js

@@ -200,9 +200,27 @@ export const ProjectSkillSchema = z
     ProjectSkillUrlSchema,
 ])
     .meta({ title: "ProjectSkill" });
+export const FusionExecutionEnvironmentSchema = z.enum([
+    "containerized",
+    "container-less",
+    "cloud",
+    "cloud-v2",
+]);
 export const checkIsNewBranch = (branch) => {
     return "projectId" in branch;
 };
+/** Identifies a single branch by its project and branch name. */
+export const BranchIdentifierSchema = z.object({
+    projectId: z.string().min(1),
+    branchName: z.string().min(1),
+});
+/** Query params for `DELETE /projects/branches`. */
+export const DeleteBranchOptionsSchema = z.object({
+    ...BranchIdentifierSchema.shape,
+    hard: z.stringbool().default(false).meta({
+        description: 'Permanently delete the branch instead of soft-deleting it ("true" / "false").',
+    }),
+});
 /**
  * Request options for `GET /projects/branches/list`. Owner/org scope comes from
  * the authenticated request context; `ownerId` here is a superuser-only override.
@@ -310,6 +328,11 @@ export const ShapeOptionSchema = z.object({
     id: z.string(),
     label: z.string(),
     effect: ShapeOptionEffectSchema.optional(),
+    /**
+     * How the client renders an option that is not a plain choice. Absent means
+     * a choice when `effect` is set, delegation otherwise.
+     */
+    kind: z.enum(["upload", "delegate", "figma-link"]).optional(),
 });
 export const ShapeQuestionSchema = z.object({
     id: z.string(),
@@ -318,10 +341,57 @@ export const ShapeQuestionSchema = z.object({
     options: z.array(ShapeOptionSchema),
     guessOptionId: z.string().optional(),
 });
+/** Figma paths that name a file, which is what the Builder Design tools read. */
+const FIGMA_FILE_PATH = /^\/(?:design|file|proto|board|slides|make)\/[A-Za-z0-9]+/;
+/**
+ * The link in canonical form, or undefined when it is not an https link to a
+ * file on figma.com. Deliberately strict: the result is written into the
+ * user's repo and handed to the agent as a requirement.
+ */
+export function parseFigmaFileUrl(value) {
+    let url;
+    try {
+        url = new URL(value.trim());
+    }
+    catch (_a) {
+        return undefined;
+    }
+    const isFigmaHost = url.hostname === "figma.com" || url.hostname === "www.figma.com";
+    if (url.protocol !== "https:" ||
+        !isFigmaHost ||
+        url.port ||
+        url.username ||
+        url.password ||
+        !FIGMA_FILE_PATH.test(url.pathname)) {
+        return undefined;
+    }
+    return url.href;
+}
+/**
+ * Lenient on purpose: users paste bare links, so any mention counts. Not one
+ * inside another URL's path or after an `@`, which would name a different host.
+ */
+const FIGMA_FILE_MENTION = /(?:^|[^a-z0-9.\/@-])(?:https?:\/\/)?((?:www\.)?figma\.com\/(?:design|file|proto|board|slides|make)\/[a-z0-9]+[^\s<>()[\]{}"'`]*)/i;
+/**
+ * The first Figma file link in `text`, canonicalized by `parseFigmaFileUrl`.
+ * Bare and `http:` mentions count as https; trailing punctuation is dropped.
+ */
+export function findFigmaFileUrl(text) {
+    var _a;
+    const mention = (_a = FIGMA_FILE_MENTION.exec(text)) === null || _a === void 0 ? void 0 : _a[1];
+    if (!mention)
+        return undefined;
+    return parseFigmaFileUrl(`https://${mention.replace(/[.,;:!?]+$/, "")}`);
+}
+export function mentionsFigmaFileUrl(text) {
+    return findFigmaFileUrl(text) !== undefined;
+}
 export const ShapeAnswerSchema = z.object({
     questionId: z.string(),
     optionId: z.string().optional(),
     designSystemId: z.string().optional(),
+    /** Set only for the Figma link option, canonicalized by `parseFigmaFileUrl`. */
+    figmaUrl: z.string().optional(),
     /**
      * Server-resolved from `designSystemId` against the caller's accessible
      * design systems. `settings.designSystems` is matched by name downstream, so
@@ -338,6 +408,7 @@ const ShapeAnswerInputBaseSchema = ShapeAnswerSchema.pick({
     questionId: true,
     optionId: true,
     designSystemId: true,
+    figmaUrl: true,
     skipped: true,
     delegated: true,
 });
@@ -354,6 +425,14 @@ export const ShapeAnswerInputSchema = z.object({
         .trim()
         .min(1)
         .optional(),
+    figmaUrl: ShapeAnswerInputBaseSchema.shape.figmaUrl
+        .unwrap()
+        .trim()
+        .max(2048)
+        .refine((value) => parseFigmaFileUrl(value) !== undefined, {
+        message: "Must be a link to a Figma file",
+    })
+        .optional(),
 });
 export const GetShapeQuestionnaireOptionsSchema = z.object({
     projectId: z.string().trim().min(1),
@@ -777,6 +856,9 @@ export const ProjectSettingsSchema = z
         authPassword: z.string().optional().meta({
             description: "Password for sites requiring authentication.",
         }),
+        branchBrowser: z.boolean().optional().meta({
+            description: "Run a headed Chrome inside every cloud branch container, which the agent drives from scripts over DevTools.",
+        }),
     })
         .optional()
         .meta({
@@ -2022,7 +2104,13 @@ export const HostingDomainSchema = z.object({
         description: "When `routeError` was last set.",
     }),
     servingConfirmedAt: z.number().optional().meta({
-        description: "When the domain was confirmed serving over HTTPS: stamped by the serving-check loop once `https://<domain>/` answers over TLS through a Builder route (or by a healthy route recreate on deploy/repair). Definitive 'serving confirmed' signal for the UI's third setup step, distinct from cert issuance (`status: active`).",
+        description: "When the domain was confirmed serving over HTTPS: stamped by the serving-check loop once `https://<domain>/` answers over TLS through a Builder route (or by a healthy route recreate on deploy/repair on an `active` domain). Definitive 'serving confirmed' signal for the UI's third setup step, distinct from cert issuance (`status: active`). Never set while `provisioning`.",
+    }),
+    certIssue: z.string().optional().meta({
+        description: "Non-fatal, user-facing reason Google's latest certificate domain-authorization attempt failed while the domain is `provisioning` (e.g. the `_acme-challenge` CNAME wasn't found). Google keeps retrying, so `status` stays `provisioning`; this drives a warning on the HTTPS step instead of a silent spinner. Cleared when an attempt stops failing or the cert is issued.",
+    }),
+    certIssueAt: z.number().optional().meta({
+        description: "When `certIssue` was last set.",
     }),
     createdBy: z.string(),
 });
@@ -2205,6 +2293,32 @@ export const EnsureMainBranchExistsOptionsSchema = z.object({
         description: "Branch whose head ref seeds the main branch when it doesn't exist yet. No-op for non-internalHost projects.",
     }),
 });
+/** Request body for `POST /projects/ensure-fusion-config`. */
+export const EnsureFusionConfigParamsSchema = z.object({
+    projectId: z.string().min(1),
+    branchName: z.string().min(1),
+    includeBackupMetadata: z.boolean().optional().meta({
+        description: "Whether to include backup metadata in the fusion config. This involves checking backup data and generating download URLs. Defaults to false.",
+    }),
+    volumeMountPath: z.string().optional().meta({
+        description: 'Volume mount path for the container. Defaults to "/app" if not specified.',
+    }),
+    isLocal: z.boolean().optional().meta({
+        description: "Flag for local execution mode. When true, adjusts paths for local execution (e.g., ./workspace instead of /app/workspace).",
+    }),
+    nativeApp: z.boolean().optional().meta({
+        description: "Flag for native app projects. When true, adds nativeApp: true to fusion config.",
+    }),
+    miseLocationPath: z.string().optional().meta({
+        description: "Path to mise installation. Provided by client from desktop app system info.",
+    }),
+    _useNI: z.boolean().optional().meta({
+        description: "Flag to use NI for package management. When true, uses NI for package management. Defaults to true.",
+    }),
+    fusionEnvironment: FusionExecutionEnvironmentSchema.optional().meta({
+        description: "Fusion environment type override. When not provided, the environment is resolved from branch/project settings.",
+    }),
+});
 /**
  * `settings.environmentVariables` is stored with **plaintext** secret values;
  * secrets are masked before this shape leaves ai-services, same as

package/src/projects.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/src/projects.spec.js

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import { DeleteBranchOptionsSchema, EnsureFusionConfigParamsSchema, } from "./projects.js";
+describe("DeleteBranchOptionsSchema", () => {
+    const ids = { projectId: "p1", branchName: "main" };
+    it("defaults hard to false", () => {
+        expect(DeleteBranchOptionsSchema.parse(ids)).toEqual({
+            ...ids,
+            hard: false,
+        });
+    });
+    it("parses hard from its query-string form", () => {
+        expect(DeleteBranchOptionsSchema.parse({ ...ids, hard: "true" }).hard).toBe(true);
+        expect(DeleteBranchOptionsSchema.parse({ ...ids, hard: "false" }).hard).toBe(false);
+    });
+    it("rejects a hard value that isn't a boolean string", () => {
+        expect(DeleteBranchOptionsSchema.safeParse({ ...ids, hard: "maybe" }).success).toBe(false);
+    });
+    it("requires a non-empty projectId and branchName", () => {
+        expect(DeleteBranchOptionsSchema.safeParse({}).success).toBe(false);
+        expect(DeleteBranchOptionsSchema.safeParse({ projectId: "", branchName: "main" })
+            .success).toBe(false);
+    });
+});
+describe("EnsureFusionConfigParamsSchema", () => {
+    const ids = { projectId: "p1", branchName: "main" };
+    it("accepts just the identifiers", () => {
+        expect(EnsureFusionConfigParamsSchema.parse(ids)).toEqual(ids);
+    });
+    it("requires a non-empty projectId and branchName", () => {
+        expect(EnsureFusionConfigParamsSchema.safeParse({ ...ids, projectId: "" })
+            .success).toBe(false);
+        expect(EnsureFusionConfigParamsSchema.safeParse({ projectId: "p1" }).success).toBe(false);
+    });
+    it("rejects an unknown fusionEnvironment", () => {
+        expect(EnsureFusionConfigParamsSchema.safeParse({
+            ...ids,
+            fusionEnvironment: "mainframe",
+        }).success).toBe(false);
+    });
+});

package/src/projects.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { AGENT_NATIVE_STARTER_REPO, getAgentNativeRootPackageJsonWriteError, getManagedDatabasePackageJsonError, getProjectState, GetShapeQuestionnaireOptionsSchema, InitialPromptSchema, isProjectDeleted, matchesAgentNativeStarter, ProjectHostingExternalSchema, ProjectHostingSchema, ProjectSettingsExternalSchema, ProjectTemplateOverridesSchema, ShapeSessionSchema, SubmitShapeAnswersOptionsSchema, } from "./projects";
+import { AGENT_NATIVE_STARTER_REPO, getAgentNativeRootPackageJsonWriteError, getManagedDatabasePackageJsonError, getProjectState, GetShapeQuestionnaireOptionsSchema, InitialPromptSchema, isProjectDeleted, matchesAgentNativeStarter, findFigmaFileUrl, mentionsFigmaFileUrl, parseFigmaFileUrl, ProjectHostingExternalSchema, ProjectHostingSchema, ProjectSettingsExternalSchema, ProjectTemplateOverridesSchema, ShapeSessionSchema, SubmitShapeAnswersOptionsSchema, } from "./projects";
 describe("project hosting schemas", () => {
     it("accepts the canonical published branch route", () => {
         expect(ProjectHostingSchema.parse({ publishedBranchId: "branch-live" })).toEqual({ publishedBranchId: "branch-live" });
@@ -112,6 +112,92 @@ describe("guided onboarding project settings", () => {
             answers: [],
         })).toThrow();
     });
+    it("accepts a Figma file link on an answer and rejects anything else", () => {
+        var _a, _b;
+        const submit = (figmaUrl) => SubmitShapeAnswersOptionsSchema.safeParse({
+            projectId: "project-1",
+            questionnaireId: "questionnaire-1",
+            answers: [
+                {
+                    questionId: "visual-style",
+                    optionId: "figma-link",
+                    figmaUrl,
+                    skipped: false,
+                    delegated: false,
+                },
+            ],
+        });
+        expect((_b = (_a = submit(" https://www.figma.com/design/AbC123/App ").data) === null || _a === void 0 ? void 0 : _a.answers[0]) === null || _b === void 0 ? void 0 : _b.figmaUrl).toBe("https://www.figma.com/design/AbC123/App");
+        expect(submit("https://example.com/design/AbC123").success).toBe(false);
+        expect(submit("").success).toBe(false);
+    });
+});
+describe("parseFigmaFileUrl", () => {
+    it.each([
+        "https://www.figma.com/design/AbC123/My-App?node-id=1-2",
+        "https://figma.com/file/AbC123/Old-Style",
+        "  https://www.figma.com/proto/AbC123/Flow  ",
+    ])("accepts %s", (value) => {
+        expect(parseFigmaFileUrl(value)).toBe(new URL(value.trim()).href);
+    });
+    it.each([
+        "",
+        "not a url",
+        "http://www.figma.com/design/AbC123/My-App",
+        "https://evil.com/figma.com/design/AbC123",
+        "https://www.figma.com.evil.com/design/AbC123",
+        "https://www.figma.com/community/file/123",
+        "https://www.figma.com/design/",
+        "https://user:pass@www.figma.com/design/AbC123",
+        "https://www.figma.com:8443/design/AbC123",
+        "javascript:alert(1)",
+    ])("rejects %j", (value) => {
+        expect(parseFigmaFileUrl(value)).toBeUndefined();
+    });
+});
+describe("mentionsFigmaFileUrl", () => {
+    it.each([
+        "Build this https://www.figma.com/design/AbC123/My-App please",
+        "from figma.com/file/AbC123",
+        "(https://figma.com/proto/AbC123)",
+    ])("finds a link in %j", (text) => {
+        expect(mentionsFigmaFileUrl(text)).toBe(true);
+    });
+    it.each([
+        "Make it look like our Figma mockups",
+        "https://notfigma.com/design/AbC123",
+        "https://www.figma.com/community",
+        "https://evil.com/figma.com/design/AbC123",
+        "https://evil.com/?next=//figma.com/design/AbC123",
+        "user@figma.com/design/AbC123",
+    ])("finds nothing in %j", (text) => {
+        expect(mentionsFigmaFileUrl(text)).toBe(false);
+    });
+});
+describe("findFigmaFileUrl", () => {
+    it.each([
+        [
+            "Build this https://www.figma.com/design/AbC123/App?node-id=1-2.",
+            "https://www.figma.com/design/AbC123/App?node-id=1-2",
+        ],
+        [
+            "from figma.com/file/AbC123/Old, thanks",
+            "https://figma.com/file/AbC123/Old",
+        ],
+        [
+            "(http://www.figma.com/proto/AbC123/Flow)",
+            "https://www.figma.com/proto/AbC123/Flow",
+        ],
+        [
+            "first https://www.figma.com/design/One/A then https://www.figma.com/design/Two/B",
+            "https://www.figma.com/design/One/A",
+        ],
+    ])("reads the link out of %j", (text, expected) => {
+        expect(findFigmaFileUrl(text)).toBe(expected);
+    });
+    it("finds nothing without a file link", () => {
+        expect(findFigmaFileUrl("Make it like our Figma mockups")).toBeUndefined();
+    });
 });
 describe("matchesAgentNativeStarter", () => {
     it("matches when repoName is the starter", () => {

package/src/single-tenancy.d.ts

@@ -56,7 +56,13 @@ export interface PrivateLinkEndpoint {
  */
 export interface VpcAwsPrivateLink extends VpcConnectionBase {
     type: "aws-privatelink";
-    /** Must match the region aws-vpc-module runs in ({@link BUILDER_AWS_REGION}). */
+    /**
+     * The region the customer's Endpoint Service lives in, as embedded in each
+     * `endpoints[].serviceName`. May differ from {@link BUILDER_AWS_REGION}: the
+     * interface endpoints always live in Builder's region and reach a remote
+     * service via cross-region PrivateLink (`service_region` in aws-vpc-module).
+     * Every endpoint in one config shares this region.
+     */
     awsRegion: string;
     endpoints: PrivateLinkEndpoint[];
     /**
@@ -219,11 +225,18 @@ export interface SingleTenancyDerivedNames {
     privateLinkEndpointIps?: Record<string, string[]>;
 }
 /**
- * The single AWS region Builder's PrivateLink infrastructure runs in. Keep in
- * sync with the `aws` provider region in packages/terraform/main.tf — an Endpoint
- * Service in another region is unreachable by our interface endpoints.
+ * The region Builder's PrivateLink interface endpoints run in. Keep in sync with
+ * the `aws` provider region in packages/terraform/main.tf. A customer's Endpoint
+ * Service in another region is still reachable via cross-region PrivateLink (the
+ * endpoint names it through `service_region`); this constant is only the
+ * *consumer* region where our endpoints and their pinned IPs live.
  */
 export declare const BUILDER_AWS_REGION = "us-east-1";
+/**
+ * AWS region id (e.g. `us-east-1`, `eu-west-2`, `ap-southeast-3`). Used to
+ * validate a config's declared service region for cross-region PrivateLink.
+ */
+export declare const AWS_REGION_RE: RegExp;
 /**
  * AWS-generated VPC Endpoint Service name: `com.amazonaws.vpce.<region>.vpce-svc-<id>`.
  * The id is 8 or 17 hex chars — AWS resource ids are never a length in between.

package/src/single-tenancy.js

@@ -1,9 +1,16 @@
 /**
- * The single AWS region Builder's PrivateLink infrastructure runs in. Keep in
- * sync with the `aws` provider region in packages/terraform/main.tf — an Endpoint
- * Service in another region is unreachable by our interface endpoints.
+ * The region Builder's PrivateLink interface endpoints run in. Keep in sync with
+ * the `aws` provider region in packages/terraform/main.tf. A customer's Endpoint
+ * Service in another region is still reachable via cross-region PrivateLink (the
+ * endpoint names it through `service_region`); this constant is only the
+ * *consumer* region where our endpoints and their pinned IPs live.
  */
 export const BUILDER_AWS_REGION = "us-east-1";
+/**
+ * AWS region id (e.g. `us-east-1`, `eu-west-2`, `ap-southeast-3`). Used to
+ * validate a config's declared service region for cross-region PrivateLink.
+ */
+export const AWS_REGION_RE = /^[a-z]{2}-[a-z]+-\d$/;
 /**
  * AWS-generated VPC Endpoint Service name: `com.amazonaws.vpce.<region>.vpce-svc-<id>`.
  * The id is 8 or 17 hex chars — AWS resource ids are never a length in between.