@avocadostudio-ai/orchestrator-core 0.21.0 → 0.22.0

package/dist/agent/sites-agent-shared.js

@@ -6,7 +6,8 @@
  */
 import { consoleLogger } from "../logger.js";
 import { mkdir, writeFile, readFile, readdir, stat } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { closeSync, existsSync, openSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { resolve, join, dirname } from "node:path";
 import { getAllBlockMeta, defaultPropsForType, validateBlockProps } from "@avocadostudio-ai/shared";
 // ── Utility helpers ──
@@ -190,7 +191,7 @@ export const THEME_PRESETS = [
  * can copy them into themeOverrides.
  */
 export function buildThemePresetsCatalog() {
-    const lines = ["### Theme Presets\nPick the preset that best matches the site's purpose and tone. Pass its `overrides` as `themeOverrides` in `bootstrap_pages`. You may tweak individual values (e.g. swap brand color) while keeping the rest of the palette.\n"];
+    const lines = ["### Theme Presets\nPick the preset that best matches the site's purpose and tone and pass its name as `themePreset` in `bootstrap_pages`. The variables below show what each one sets and are the token names to use in `themeOverrides` for a tweak on top (e.g. swap `--brand`).\n"];
     for (const preset of THEME_PRESETS) {
         const overridesJson = JSON.stringify(preset.overrides, null, 2);
         lines.push(`#### ${preset.name}\n${preset.description}\n\`\`\`json\n${overridesJson}\n\`\`\``);
@@ -198,7 +199,7 @@ export function buildThemePresetsCatalog() {
             lines.push(`Google Fonts: \`${preset.googleFontsUrl}\`\n`);
         }
     }
-    lines.push(`\n**Custom tweaks are encouraged.** If the user says "nature site but teal", start from \`forest\` and swap \`--brand\` to teal. Always keep hover/subtle/fg consistent with the brand hue.`);
+    lines.push(`\n**Custom tweaks are encouraged.** If the user says "nature site but teal", pass \`themePreset: "forest"\` and \`themeOverrides: { "--brand": "<teal>" }\`; hover, subtle and foreground follow the brand automatically.`);
     return lines.join("\n");
 }
 // ── Sites agent model tiers ──
@@ -269,6 +270,42 @@ Extract URLs, site names, and scope constraints from the message. If not present
     }
 }
 // ── CSS variable persistence ──
+/*
+ * The page itself, painted from the theme. Without it `body` is transparent
+ * and any section that does not paint its own background shows the browser's
+ * white — invisible on a light theme, a white band down a dark one.
+ */
+const PAGE_CANVAS_MARKER = "/* page canvas */";
+const PAGE_CANVAS_RULE = `${PAGE_CANVAS_MARKER}
+html,
+body {
+  background: var(--bg-0);
+  color: var(--body);
+}`;
+/**
+ * A theme that names a web font without importing it renders in the fallback,
+ * and nothing says so. Build the import for any family not already loaded.
+ * Weighted first, checked against Google, because one family that lacks a
+ * requested weight fails the whole stylesheet; unweighted if that is refused
+ * or the network is unavailable.
+ */
+async function importForNamedWebFonts(vars, css) {
+    const { webFontFamily, googleFontsUrlFor } = await import("./site-theme-resolve.js");
+    const families = [vars["--font-heading"], vars["--font-body"]]
+        .map(webFontFamily)
+        .filter((f) => f !== null)
+        .filter((f) => !css.includes(`family=${f.replace(/ /g, "+")}`));
+    if (families.length === 0)
+        return undefined;
+    const weighted = googleFontsUrlFor(families, true);
+    try {
+        const res = await fetch(weighted, { signal: AbortSignal.timeout(3_000) });
+        if (res.ok)
+            return weighted;
+    }
+    catch { /* offline — fall through */ }
+    return googleFontsUrlFor(families, false);
+}
 export async function patchGlobalsCssVars(cssPath, vars) {
     if (!existsSync(cssPath))
         return;
@@ -280,19 +317,17 @@ export async function patchGlobalsCssVars(cssPath, vars) {
     css = css.replace(/\.dark\s*\{[^}]*\}/g, "");
     css = css.replace(/\n{3,}/g, "\n\n"); // collapse leftover blank lines
     // Handle Google Fonts import — inject @import url(...) after @import "tailwindcss"
-    const googleFontsUrl = vars["--google-fonts-import"];
+    let googleFontsUrl = vars["--google-fonts-import"];
+    if (!googleFontsUrl)
+        googleFontsUrl = await importForNamedWebFonts(vars, css);
     if (googleFontsUrl) {
         // Remove existing Google Fonts imports to avoid duplicates
         css = css.replace(/@import\s+url\(["']https:\/\/fonts\.googleapis\.com[^)]*\);\s*\n?/g, "");
-        // Insert after the last @import line
-        const lastImportIdx = css.lastIndexOf("@import");
-        if (lastImportIdx >= 0) {
-            const lineEnd = css.indexOf("\n", lastImportIdx);
-            css = css.slice(0, lineEnd + 1) + `@import url("${googleFontsUrl}");\n` + css.slice(lineEnd + 1);
-        }
-        else {
-            css = `@import url("${googleFontsUrl}");\n` + css;
-        }
+        // First line of the file, never after `@import "tailwindcss"`. Tailwind
+        // inlines its imports, so anything below them compiles to an @import
+        // after thousands of lines of rules — which browsers ignore. Every theme
+        // font this agent chose rendered in the fallback for exactly that reason.
+        css = `@import url("${googleFontsUrl}");\n` + css;
     }
     for (const [prop, value] of Object.entries(vars)) {
         if (prop === "--google-fonts-import")
@@ -306,7 +341,35 @@ export async function patchGlobalsCssVars(cssPath, vars) {
             css = css.replace(/(:root\s*\{[^}]*)(\})/, `$1  ${prop}: ${value};\n$2`);
         }
     }
+    if (!css.includes(PAGE_CANVAS_MARKER))
+        css = `${css.trimEnd()}\n\n${PAGE_CANVAS_RULE}\n`;
     await writeFile(cssPath, css, "utf-8");
+    if (vars["--brand"])
+        await recolorGeneratedMonograms(join(dirname(cssPath), "..", "public"), vars["--brand"], vars["--brand-fg"]);
+}
+/**
+ * The scaffold's logo and favicon are monogram SVGs shown through `<img>`,
+ * which cannot see the page's CSS variables — so `fill="var(--brand, …)"`
+ * always rendered its fallback blue, whatever brand the theme chose. Bake the
+ * brand in. Only a generated monogram (a rect plus initials) is touched; a
+ * downloaded or hand-made logo is left alone.
+ */
+async function recolorGeneratedMonograms(publicDir, brand, fg) {
+    if (!/^#[0-9a-f]{3,8}$/i.test(brand.trim()))
+        return;
+    for (const file of ["logo.svg", "favicon.svg"]) {
+        const path = join(publicDir, file);
+        if (!existsSync(path))
+            continue;
+        const svg = await readFile(path, "utf-8");
+        if (!/^<svg[^>]*>\s*<rect[^>]*\/>\s*<text[^>]*>[A-Za-z0-9]{1,3}<\/text>\s*<\/svg>\s*$/.test(svg))
+            continue;
+        let next = svg.replace(/(<rect[^>]*fill=")[^"]*(")/, `$1${brand.trim()}$2`);
+        if (fg && /^#[0-9a-f]{3,8}$/i.test(fg.trim()))
+            next = next.replace(/(<text[^>]*fill=")[^"]*(")/, `$1${fg.trim()}$2`);
+        if (next !== svg)
+            await writeFile(path, next, "utf-8");
+    }
 }
 // ── Schema validation + auto-correction ──
 const PROP_RENAME_RULES = {
@@ -441,7 +504,30 @@ export function normalizePageBlocks(blocks, log = consoleLogger()) {
     return { contentBlocks, footerBlock, strippedCount };
 }
 // ── Site scaffolding templates ──
-export function packageJson(siteId, name, port) {
+/**
+ * The zod a new site must use: exactly the one `@avocadostudio-ai/shared`
+ * resolves. Zod 4 brands its minor version into its types, so a site on
+ * another minor makes every `registerBlock` schema a cross-version type
+ * comparison. With `^4.3.6` a fresh site resolved 4.6.4 against shared's
+ * 4.3.6, and `tsc` on it ran out of heap — which failed the repo's
+ * typecheck, and the agent's own verification of every custom block.
+ */
+/** What a dev server or a typecheck leaves behind — never a project on its own. */
+const BUILD_LEFTOVERS = new Set([".next", "node_modules", "tsconfig.tsbuildinfo", "next-env.d.ts", ".turbo"]);
+/** An existing site project to reuse, as opposed to a leftover directory. */
+export function isSiteProject(projectDir) {
+    return existsSync(join(projectDir, "package.json"));
+}
+export function sharedZodVersion(root = monorepoRoot()) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, "packages/shared/node_modules/zod/package.json"), "utf-8"));
+        if (pkg.version)
+            return pkg.version;
+    }
+    catch { /* not installed here — fall back */ }
+    return "4.3.6";
+}
+export function packageJson(siteId, name, port, zodVersion = sharedZodVersion()) {
     return JSON.stringify({
         name: `@ai-site-editor/${siteId}`,
         version: "0.0.1",
@@ -450,7 +536,7 @@ export function packageJson(siteId, name, port) {
         scripts: { dev: `next dev -p ${port}`, build: "next build", start: `next start -p ${port}`, typecheck: "tsc --noEmit" },
         dependencies: {
             "@avocadostudio-ai/blocks": "workspace:*", "@avocadostudio-ai/shared": "workspace:*", "@avocadostudio-ai/site-sdk": "workspace:*",
-            "@tailwindcss/postcss": "^4.2.1", next: "15.2.8", react: "^19.0.0", "react-dom": "^19.0.0", tailwindcss: "^4.2.1", zod: "^4.3.6",
+            "@tailwindcss/postcss": "^4.2.1", next: "15.2.8", react: "^19.0.0", "react-dom": "^19.0.0", tailwindcss: "^4.2.1", zod: zodVersion,
         },
         devDependencies: { "@types/node": "^22.13.10", "@types/react": "^19.0.10", "@types/react-dom": "^19.0.4", typescript: "^5.7.3" },
     }, null, 2) + "\n";
@@ -599,6 +685,8 @@ export function globalsCss() {
   --surface: #1e293b; --surface-border: #334155; --border: #334155; --card-bg: #1e293b; --card-shadow: 0 1px 3px rgba(0,0,0,0.3); --hero-bg: var(--bg-0); --cta-bg: var(--bg-100); --placeholder-img: #334155;
   --footer-bg: #020617; --footer-text: #94a3b8; --footer-heading: #e2e8f0; --footer-link: #64748b; --footer-link-hover: #cbd5e1; --footer-border: #1e293b;
 }
+
+${PAGE_CANVAS_RULE}
 `;
 }
 export function defaultsTs(siteId, siteName) {
@@ -812,7 +900,18 @@ export async function scaffoldSiteProject(options) {
     const root = monorepoRoot();
     const projectDir = join(root, "apps", siteId);
     if (existsSync(projectDir)) {
-        throw new Error(`Directory apps/${siteId} already exists`);
+        // A directory holding only build output is what a dev server leaves when
+        // it outlives its site being deleted: a worker writes .next back. It is
+        // not a project, and refusing it made create_site fail until the agent
+        // rm -rf'd it by hand.
+        const entries = await readdir(projectDir);
+        if (entries.every((e) => BUILD_LEFTOVERS.has(e))) {
+            const { rm } = await import("node:fs/promises");
+            await rm(projectDir, { recursive: true, force: true });
+        }
+        else {
+            throw new Error(`Directory apps/${siteId} already exists`);
+        }
     }
     const port = options.port || await findAvailablePort(root);
     await mkdir(projectDir, { recursive: true });
@@ -1042,6 +1141,14 @@ export async function detectSitePort(projectDir) {
 /**
  * Start a Next.js dev server and wait for it to report "Ready" (or timeout).
  * Replaces fire-and-forget spawn patterns that reported success before the server was up.
+ *
+ * The server writes to a log file, never to a pipe back to this process. The
+ * server is detached so it outlives its launcher, but a pipe does not: in CLI
+ * mode the launcher is the short-lived MCP stdio server the Claude CLI spawns,
+ * and once it exited nobody drained the pipe. The server kept listening and
+ * hung on its first request, so the agent reported "Site running at :3500"
+ * over a site that never answered. An orchestrator restart did the same to
+ * every site the SDK path had started.
  */
 export async function startAndWaitForDevServer(opts) {
     const log = opts.logger ?? consoleLogger();
@@ -1049,10 +1156,12 @@ export async function startAndWaitForDevServer(opts) {
     const args = opts.useFilter
         ? ["--filter", `@ai-site-editor/${opts.siteId}`, "dev"]
         : ["dev"];
-    // Kill any existing process on the port first
+    // Kill whatever is listening on the port first. Listeners only: a bare
+    // `lsof -ti:<port>` also names every client connected to it, which can be
+    // the orchestrator itself.
     try {
         const { execSync } = await import("node:child_process");
-        const pids = execSync(`lsof -ti:${opts.port} 2>/dev/null`, { encoding: "utf-8" }).trim();
+        const pids = execSync(`lsof -ti:${opts.port} -sTCP:LISTEN 2>/dev/null`, { encoding: "utf-8" }).trim();
         if (pids) {
             for (const pid of pids.split("\n")) {
                 try {
@@ -1064,10 +1173,14 @@ export async function startAndWaitForDevServer(opts) {
         }
     }
     catch { /* no process on port — fine */ }
-    log.info(`[sites-agent] Starting dev server for ${opts.siteId} on port ${opts.port}...`);
+    const logDir = join(tmpdir(), "avocado-dev-servers");
+    await mkdir(logDir, { recursive: true });
+    const logFile = join(logDir, `${opts.siteId}.log`);
+    const out = openSync(logFile, "w");
+    log.info(`[sites-agent] Starting dev server for ${opts.siteId} on port ${opts.port} (log: ${logFile})...`);
     const devProcess = spawn("pnpm", args, {
         cwd: opts.cwd,
-        stdio: ["ignore", "pipe", "pipe"],
+        stdio: ["ignore", out, out],
         detached: true,
         env: {
             ...process.env,
@@ -1080,25 +1193,33 @@ export async function startAndWaitForDevServer(opts) {
             CHOKIDAR_INTERVAL: "1000",
         },
     });
+    // The child holds its own copy of the descriptor.
+    closeSync(out);
     devProcess.unref();
     let serverReady = false;
     const timeoutMs = opts.timeoutMs ?? 60_000;
     await new Promise((resolve) => {
-        const timer = setTimeout(() => resolve(), timeoutMs);
-        const onData = (chunk) => {
-            const text = chunk.toString();
-            if (text.includes("Ready") || text.includes(`localhost:${opts.port}`)) {
-                serverReady = true;
-                clearTimeout(timer);
-                devProcess.stdout?.removeAllListeners();
-                devProcess.stderr?.removeAllListeners();
-                resolve();
-            }
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            clearInterval(poll);
+            devProcess.off("exit", finish);
+            resolve();
         };
-        devProcess.stdout?.on("data", onData);
-        devProcess.stderr?.on("data", onData);
-        devProcess.on("exit", () => { clearTimeout(timer); resolve(); });
+        const timer = setTimeout(finish, timeoutMs);
+        const poll = setInterval(() => {
+            readFile(logFile, "utf-8").then((text) => {
+                if (text.includes("Ready") || text.includes(`localhost:${opts.port}`)) {
+                    serverReady = true;
+                    finish();
+                }
+            }, () => { });
+        }, 250);
+        devProcess.on("exit", finish);
     });
     log.info(`[sites-agent] Dev server ${serverReady ? "ready" : "timed out"} for ${opts.siteId} at http://localhost:${opts.port}`);
-    return { serverReady };
+    return { serverReady, logFile };
 }

package/dist/agent/sites-agent-tools.js

@@ -19,7 +19,9 @@ import { saveScreenshot } from "../migration/migration-tools.js";
 import { scopedSessionKey, setPage, bumpVersion, getSiteConfig, setSiteConfig } from "../state/session-state.js";
 import { listImages as listGdriveImages, downloadImage as downloadGdriveImage, isGdriveConfigured, resolveGdriveFolderId, fileNameToAlt, } from "../image/gdrive-client.js";
 import sharp from "sharp";
-import { sanitizeSiteId, monorepoRoot, findAvailablePort, patchGlobalsCssVars, validateAndCorrectProps, fixFooterLinks, analyzeCodebase, cloneRepo, detectSitePort, startAndWaitForDevServer, getDraftModeSecret, packageJson, nextConfigTs, tsconfigJson, postcssConfig, layoutTsx, globalsCss, defaultsTs, editorApiRoute, pageTsx, hybridPageTsx, blocksRegisterTsx, samplePagesJson, defaultLogoSvg, faviconSvg, } from "./sites-agent-shared.js";
+import { sanitizeSiteId, monorepoRoot, findAvailablePort, patchGlobalsCssVars, validateAndCorrectProps, fixFooterLinks, analyzeCodebase, cloneRepo, detectSitePort, startAndWaitForDevServer, getDraftModeSecret, isSiteProject, packageJson, nextConfigTs, tsconfigJson, postcssConfig, layoutTsx, globalsCss, defaultsTs, editorApiRoute, pageTsx, hybridPageTsx, blocksRegisterTsx, samplePagesJson, defaultLogoSvg, faviconSvg, } from "./sites-agent-shared.js";
+import { findStockPhotos } from "./stock-photos.js";
+import { resolveThemeVars, normalizeSiteSlug, normalizeNavLabels, normalizeNavGroups, THEME_PRESET_NAMES } from "./site-theme-resolve.js";
 /** Convert a package name like "coastal-villa-web" → "Coastal Villa Web" */
 function humanizePkgName(name) {
     return name
@@ -134,7 +136,7 @@ export function createSitesAgentMcpServer(options) {
             const root = monorepoRoot();
             const projectDir = join(root, "apps", siteId);
             let existingPort = 0;
-            if (existsSync(projectDir)) {
+            if (isSiteProject(projectDir)) {
                 // Clean content from previous migration but keep project skeleton (package.json, node_modules, etc.)
                 const { rm } = await import("node:fs/promises");
                 for (const dir of ["content", "blocks", "public/images", ".next"]) {
@@ -154,6 +156,13 @@ export function createSitesAgentMcpServer(options) {
                     catch { /* use new port */ }
                 }
             }
+            else if (existsSync(join(projectDir, ".next"))) {
+                // Not a project, just build output a dev server wrote back after its
+                // site was deleted. A stale .next under a fresh scaffold serves the
+                // old site's chunks.
+                const { rm } = await import("node:fs/promises");
+                await rm(join(projectDir, ".next"), { recursive: true, force: true });
+            }
             // Validate requested/existing port is actually free; fall back to auto-assign
             let port = args.port || existingPort || 0;
             if (port) {
@@ -387,7 +396,8 @@ export function createSitesAgentMcpServer(options) {
                 ogImage: z.string().optional().describe("Open Graph image URL"),
             }).optional().describe("SEO metadata for the page"),
         })),
-        themeOverrides: z.record(z.string(), z.string()).optional().describe("CSS variable overrides for theming"),
+        themePreset: z.enum(THEME_PRESET_NAMES).optional().describe("Name of a theme preset to apply in full (palette, fonts and their import, radii). Prefer this over copying a preset's variables; use themeOverrides only for tweaks on top, e.g. a different --brand."),
+        themeOverrides: z.record(z.string(), z.string()).optional().describe("CSS variable overrides for theming, applied over themePreset. Use the preset token names (--bg-0, --heading, --body, --brand, --font-heading, …); hover/subtle shades and dark-background text are derived."),
         navLabels: z.record(z.string(), z.string()).optional().describe("Custom nav labels per slug, e.g. { '/about': 'Über uns', '/events/teamevent': 'Teamevent' }. Overrides auto-generated labels."),
         navGroups: z.record(z.string(), z.array(z.string())).optional().describe("Group child pages under a parent nav dropdown, e.g. { 'Events': ['/events/teamevent', '/events/polterabend'] }. Parent has no href, children shown in dropdown."),
         siteLogo: z.string().optional().describe("Logo URL (relative, e.g. '/images/logo.png'). Set after downloading with download_remote_image."),
@@ -397,6 +407,18 @@ export function createSitesAgentMcpServer(options) {
         constraints: z.array(z.string()).optional().describe("Content rules the AI must follow, e.g. ['Always use Swiss German spelling', 'Never discount below CHF 49']"),
     }, async (args) => {
         try {
+            // Normalize what the agent wrote before anything reads it: `index` is
+            // the home page, nav keys are routes, and theme values are resolved to
+            // the tokens blocks actually read (see site-theme-resolve.ts).
+            for (const page of args.pages)
+                page.slug = normalizeSiteSlug(page.slug);
+            args.navLabels = normalizeNavLabels(args.navLabels);
+            args.navGroups = normalizeNavGroups(args.navGroups);
+            const theme = args.themePreset || (args.themeOverrides && Object.keys(args.themeOverrides).length > 0)
+                ? resolveThemeVars(args.themeOverrides, { preset: args.themePreset })
+                : null;
+            if (theme)
+                args.themeOverrides = theme.vars;
             const totalBlocks = args.pages.reduce((sum, p) => sum + p.blocks.length, 0);
             const slugs = args.pages.map(p => p.slug);
             log.info(`[bootstrap_pages] START siteId=${args.siteId} pages=${args.pages.length} blocks=${totalBlocks} slugs=[${slugs.join(", ")}]`);
@@ -594,6 +616,7 @@ export function createSitesAgentMcpServer(options) {
                             pagesCreated: createdPages,
                             totalBlocks: totalBlocksFinal,
                             persistedToFile: true,
+                            ...(theme?.notes.length ? { themeNotes: theme.notes } : {}),
                         }),
                     }],
             };
@@ -624,6 +647,26 @@ export function createSitesAgentMcpServer(options) {
             return { content: [{ type: "text", text: JSON.stringify({ localUrl: args.url, error: "Download failed, using original URL" }) }] };
         }
     }, { annotations: { destructiveHint: false, openWorldHint: true } });
+    // ── STOCK PHOTOS ──
+    const findStockPhotosTool = tool("find_stock_photos", "Find stock photos by search query and download them into the site, in one call. Use this for every photo on a new site unless the user supplied images: never pass download_remote_images a URL you did not get from a tool — an Unsplash URL from memory resolves to an unrelated photo. Queries are keyword searches: two to four concrete words naming the subject (\"pediatric dentist child\", \"dental clinic interior\"); long descriptive phrases find nothing. Each result carries the photo's own description: if it does not match the use, search again with a different query rather than use it.", {
+        siteId: z.string().describe("Site ID — photos saved to apps/{siteId}/public/images/"),
+        photos: z.array(z.object({
+            query: z.string().min(2).describe("Two to four keywords naming the subject, e.g. \"dentist child smiling\""),
+            alt: z.string().optional().describe("Alt text for the page"),
+            orientation: z.enum(["landscape", "portrait", "squarish"]).optional().describe("landscape (default) for heroes and wide cards, squarish for team portraits"),
+        })).min(1).max(20),
+    }, async (args) => {
+        const outputDir = join(monorepoRoot(), "apps", args.siteId, "public", "images");
+        await mkdir(outputDir, { recursive: true });
+        const results = await findStockPhotos({
+            siteId: args.siteId, photos: args.photos, outputDir, download: downloadImage,
+            accessKey: process.env.UNSPLASH_ACCESS_KEY?.trim() || undefined,
+            orchestratorUrl: process.env.ORCHESTRATOR_URL,
+        });
+        const succeeded = results.filter((r) => r.localUrl).length;
+        emitPhaseOutcome?.({ tool: "find_stock_photos", data: { succeeded, total: results.length } });
+        return { content: [{ type: "text", text: JSON.stringify({ results, succeeded, failed: results.length - succeeded }) }] };
+    }, { annotations: { destructiveHint: false, openWorldHint: true } });
     // ── BATCH DOWNLOAD IMAGES ──
     const downloadImagesTool = tool("download_remote_images", "Download multiple remote images in one call. Much more efficient than calling download_remote_image repeatedly — use this when you have 3+ images to download. Returns an array of { url, localUrl } mappings.", {
         siteId: z.string().describe("Site ID — images saved to apps/{siteId}/public/images/"),
@@ -730,7 +773,10 @@ export function createSitesAgentMcpServer(options) {
     const applyThemeTool = tool("apply_theme", "Apply CSS custom property overrides to a site's theme. These are injected into the preview so blocks render with the migrated site's colors and fonts.", {
         siteId: z.string().describe("Site ID to apply theme to"),
         variables: z.record(z.string(), z.string()).describe("CSS variable overrides, e.g. { '--brand': '#2563eb' }"),
+        preset: z.enum(THEME_PRESET_NAMES).optional().describe("Theme preset to apply first; variables override it."),
     }, async (args) => {
+        const theme = resolveThemeVars(args.variables, { preset: args.preset });
+        args.variables = theme.vars;
         const sessionKey = scopedSessionKey(session, args.siteId);
         const existing = getSiteConfig(sessionKey);
         setSiteConfig(sessionKey, {
@@ -747,7 +793,7 @@ export function createSitesAgentMcpServer(options) {
         return {
             content: [{
                     type: "text",
-                    text: JSON.stringify({ status: "applied", variableCount: Object.keys(args.variables).length, persistedToCss: true }),
+                    text: JSON.stringify({ status: "applied", variableCount: Object.keys(args.variables).length, persistedToCss: true, ...(theme.notes.length ? { themeNotes: theme.notes } : {}) }),
                 }],
         };
     }, { annotations: { destructiveHint: false, openWorldHint: false } });
@@ -979,7 +1025,7 @@ export function createSitesAgentMcpServer(options) {
             // Check if port is in use — find a free one
             try {
                 const { execSync } = await import("node:child_process");
-                const pids = execSync(`lsof -ti:${port} 2>/dev/null`, { encoding: "utf-8" }).trim();
+                const pids = execSync(`lsof -ti:${port} -sTCP:LISTEN 2>/dev/null`, { encoding: "utf-8" }).trim();
                 if (pids) {
                     log.info(`[integrate_site] Port ${port} in use, finding free port...`);
                     port = await findAvailablePort(root, log);
@@ -1050,7 +1096,7 @@ export function createSitesAgentMcpServer(options) {
             // Check if port is in use — if so, find a free one and update package.json
             try {
                 const { execSync } = await import("node:child_process");
-                const pids = execSync(`lsof -ti:${port} 2>/dev/null`, { encoding: "utf-8" }).trim();
+                const pids = execSync(`lsof -ti:${port} -sTCP:LISTEN 2>/dev/null`, { encoding: "utf-8" }).trim();
                 if (pids) {
                     log.info(`[sites-agent] Port ${port} in use, finding free port...`);
                     port = await findAvailablePort(root, log);
@@ -1121,7 +1167,7 @@ export function createSitesAgentMcpServer(options) {
             // Kill any existing process on the allocated port
             try {
                 const { execSync } = await import("node:child_process");
-                const pids = execSync(`lsof -ti:${port} 2>/dev/null`, { encoding: "utf-8" }).trim();
+                const pids = execSync(`lsof -ti:${port} -sTCP:LISTEN 2>/dev/null`, { encoding: "utf-8" }).trim();
                 if (pids) {
                     for (const pid of pids.split("\n")) {
                         try {
@@ -1227,7 +1273,7 @@ export function createSitesAgentMcpServer(options) {
     return createSdkMcpServer({
         name: "sites-agent",
         version: "1.0.0",
-        tools: [listSitesTool, discoverStructureTool, createSiteTool, scrapeUrlTool, extractTokensTool, bootstrapPagesTool, downloadImageTool, downloadImagesTool, browseGdriveTool, applyThemeTool, analyzeCodebaseTool, cloneRepoTool, integrateSiteTool, launchSiteTool, registerSiteTool, visualQaDiffTool, ...createMigrationTools()],
+        tools: [listSitesTool, discoverStructureTool, createSiteTool, scrapeUrlTool, extractTokensTool, bootstrapPagesTool, downloadImageTool, downloadImagesTool, findStockPhotosTool, browseGdriveTool, applyThemeTool, analyzeCodebaseTool, cloneRepoTool, integrateSiteTool, launchSiteTool, registerSiteTool, visualQaDiffTool, ...createMigrationTools()],
     });
 }
 // Template functions now live in sites-agent-shared.ts — imported at the top of this file.

package/dist/agent/stock-photos.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Stock photography for a site built from a sentence.
+ *
+ * Create mode had no way to find a photo: the prompt said "use one shared
+ * style phrase in every image search", but no tool searched anything, so the
+ * agent handed `download_remote_images` Unsplash URLs recalled from memory.
+ * Those resolve to whatever photo now owns the id. A children's dental
+ * practice got vintage cars, a sparkler and a truck dashboard as its team.
+ *
+ * This searches first and downloads what the search returned, and hands back
+ * each photo's own description so the agent can see a mismatch rather than
+ * trust a URL it made up.
+ */
+export type StockPhotoRequest = {
+    query: string;
+    alt?: string;
+    orientation?: "landscape" | "portrait" | "squarish";
+};
+export type StockPhotoResult = {
+    query: string;
+    localUrl?: string;
+    /** What the photo shows, from Unsplash — check it matches the use. */
+    description?: string;
+    author?: string;
+    error?: string;
+};
+type Candidate = {
+    id: string;
+    url: string;
+    description: string;
+    author: string;
+};
+type SearchDeps = {
+    fetchImpl?: typeof fetch;
+    /** Direct Unsplash access; without it the orchestrator's proxy is asked. */
+    accessKey?: string;
+    orchestratorUrl?: string;
+};
+export declare function searchStockPhotos(req: StockPhotoRequest, deps?: SearchDeps): Promise<Candidate[]>;
+/**
+ * Unsplash matches keywords: "pediatric dentist with child patient, bright
+ * clinic" finds nothing, "pediatric dentist" finds hundreds. Try the query as
+ * given, then its first clause, then its first three and two words.
+ */
+export declare function queryFallbacks(query: string): string[];
+export declare function findStockPhotos(opts: {
+    siteId: string;
+    photos: StockPhotoRequest[];
+    outputDir: string;
+    download: (url: string, alt: string | undefined, outputDir: string) => Promise<{
+        fileName: string;
+    }>;
+} & SearchDeps): Promise<StockPhotoResult[]>;
+export {};

package/dist/agent/stock-photos.js

@@ -0,0 +1,75 @@
+/**
+ * Stock photography for a site built from a sentence.
+ *
+ * Create mode had no way to find a photo: the prompt said "use one shared
+ * style phrase in every image search", but no tool searched anything, so the
+ * agent handed `download_remote_images` Unsplash URLs recalled from memory.
+ * Those resolve to whatever photo now owns the id. A children's dental
+ * practice got vintage cars, a sparkler and a truck dashboard as its team.
+ *
+ * This searches first and downloads what the search returned, and hands back
+ * each photo's own description so the agent can see a mismatch rather than
+ * trust a URL it made up.
+ */
+export async function searchStockPhotos(req, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const q = encodeURIComponent(req.query.trim());
+    if (deps.accessKey) {
+        const res = await fetchImpl(`https://api.unsplash.com/search/photos?query=${q}&orientation=${req.orientation ?? "landscape"}&per_page=10&content_filter=high`, { headers: { Authorization: `Client-ID ${deps.accessKey}`, "Accept-Version": "v1" }, signal: AbortSignal.timeout(10_000) });
+        if (!res.ok)
+            throw new Error(`Unsplash search answered ${res.status}`);
+        const payload = (await res.json());
+        return (payload.results ?? [])
+            .filter((r) => r.id && r.urls?.regular)
+            .map((r) => ({ id: r.id, url: r.urls.regular, description: r.alt_description ?? r.description ?? "", author: r.user?.name ?? "Unsplash" }));
+    }
+    const base = deps.orchestratorUrl ?? "http://localhost:4200";
+    const res = await fetchImpl(`${base}/unsplash/search?q=${q}&limit=10`, { signal: AbortSignal.timeout(10_000) });
+    if (!res.ok)
+        throw new Error(res.status === 404 ? "stock photo search is not configured (UNSPLASH_ACCESS_KEY)" : `photo search answered ${res.status}`);
+    const payload = (await res.json());
+    return (payload.items ?? []).map((i) => ({ id: i.id, url: i.imageUrl, description: i.alt ?? "", author: i.author ?? "Unsplash" }));
+}
+/**
+ * Unsplash matches keywords: "pediatric dentist with child patient, bright
+ * clinic" finds nothing, "pediatric dentist" finds hundreds. Try the query as
+ * given, then its first clause, then its first three and two words.
+ */
+export function queryFallbacks(query) {
+    const full = query.trim().replace(/\s+/g, " ");
+    const clause = full.split(/[,;.]/)[0].trim();
+    const words = clause.split(" ").filter((w) => !/^(with|and|of|in|at|for|the|a|an|on)$/i.test(w));
+    return [...new Set([full, clause, words.slice(0, 3).join(" "), words.slice(0, 2).join(" ")])].filter(Boolean);
+}
+/** Photo ids already placed on each site, so a second call does not repeat one. */
+const usedBySite = new Map();
+export async function findStockPhotos(opts) {
+    const used = usedBySite.get(opts.siteId) ?? new Set();
+    usedBySite.set(opts.siteId, used);
+    const results = [];
+    // In order, not in parallel: two requests for similar subjects must not
+    // both pick the same top hit.
+    for (const req of opts.photos) {
+        try {
+            let candidates = [];
+            let pick;
+            for (const query of queryFallbacks(req.query)) {
+                candidates = await searchStockPhotos({ ...req, query }, opts);
+                pick = candidates.find((c) => !used.has(c.id));
+                if (pick)
+                    break;
+            }
+            if (!pick) {
+                results.push({ query: req.query, error: candidates.length ? "every match is already used on this site" : "no match — try a broader query" });
+                continue;
+            }
+            used.add(pick.id);
+            const file = await opts.download(pick.url, req.alt ?? pick.description, opts.outputDir);
+            results.push({ query: req.query, localUrl: `/images/${file.fileName}`, description: pick.description, author: pick.author });
+        }
+        catch (e) {
+            results.push({ query: req.query, error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    return results;
+}

package/dist/chat/anthropic-planner.js

@@ -250,6 +250,7 @@ export async function generatePlanWithAnthropic(args) {
         locale: args.locale,
         imageSourceChoiceOpen: args.imageSourceChoiceOpen,
         attachmentCount: args.contextPack.attachments?.length,
+        attachmentImages: args.contextPack.attachments?.filter((attachment) => attachment.kind === "image").map(({ url, name }) => ({ url, name })),
     });
     // Stable prefix carries cache_control; dynamic tail is sent as a second
     // text block without it, so per-request flags don't bust the cached prefix.

package/dist/chat/chat-pipeline-context.d.ts

@@ -45,15 +45,12 @@ export declare function compactPlannerContextPack(args: {
             type: import("@avocadostudio-ai/shared").BlockType;
         } | null;
     };
-    pageOutline: {
+    pageOutline: ({
         id: string;
-        type: import("@avocadostudio-ai/shared").BlockType;
+        type: string;
         props: Record<string, unknown>;
-        arrayProps: Record<string, {
-            length: number;
-            labels?: string[];
-        }>;
-    }[];
+        arrayProps: ReturnType<typeof import("../nlp/deterministic-planner-context.ts").arrayPropLengths>;
+    } & import("../nlp/deterministic-planner-context.ts").BlockConstraintNote)[];
     pageMeta: import("@avocadostudio-ai/shared").PageMeta | null;
     pageObservations: import("../nlp/intent-detection.ts").PageObservation[];
     pageIntent: string;
@@ -123,15 +120,12 @@ export declare function minimalPlannerContextPack(args: {
             type: import("@avocadostudio-ai/shared").BlockType;
         } | null;
     };
-    pageOutline: {
+    pageOutline: ({
         id: string;
-        type: import("@avocadostudio-ai/shared").BlockType;
+        type: string;
         props: Record<string, unknown>;
-        arrayProps: Record<string, {
-            length: number;
-            labels?: string[];
-        }>;
-    }[];
+        arrayProps: ReturnType<typeof import("../nlp/deterministic-planner-context.ts").arrayPropLengths>;
+    } & import("../nlp/deterministic-planner-context.ts").BlockConstraintNote)[];
     pageMeta: import("@avocadostudio-ai/shared").PageMeta | null;
     pageObservations: import("../nlp/intent-detection.ts").PageObservation[];
     pageIntent: string;