feat: add ai-generated image placeholder feature (#845)

Author: jeremydw

.agent/rules/documentation.md

@@ -0,0 +1,74 @@
+---
+trigger: always_on
+---
+
+# Root.js Project Overview
+
+Root.js is a full-featured web development tool with a built-in CMS, designed for building modern, performant websites.
+
+## Key Features
+
+- **TSX Rendering**: Uses TSX for server-side rendering and templating.
+- **Web Components**: Supports standard Web Components for building UI elements.
+- **File Routes**: Intuitive file-based routing system.
+- **i18n**: Built-in support for internationalization.
+- **CMS**: Integrated Content Management System for managing content.
+
+## Project Structure
+
+The project is a monorepo managed with `pnpm` and `turbo`.
+
+### Packages (`packages/`)
+
+- **@blinkk/root** (`packages/root`): The core framework package.
+- **@blinkk/root-cms** (`packages/root-cms`): The CMS integration for Root.js.
+- **@blinkk/create-root** (`packages/create-root`): CLI tool to scaffold new Root.js projects.
+
+### Documentation (`docs/`)
+
+Contains documentation for the project, likely powering `rootjs.dev`.
+
+### Examples (`examples/`)
+
+Contains example projects demonstrating various features of Root.js.
+
+## Development
+
+- **Package Manager**: `pnpm`
+- **Build System**: `turbo`
+- **Linting**: `eslint`
+
+## Best Practices for Agents
+
+When working on this project, please adhere to the following guidelines:
+
+### Package Management
+
+- **Always use `pnpm`**: This project uses `pnpm` for package management. Do not use `npm` or `yarn`.
+- **Install dependencies**: Run `pnpm install` at the root to install dependencies for all packages.
+- **Update types**: Use `pnpm types` within Root CMS projects to regenerate types.
+
+### Build & Test
+
+- **Use Turbo**: Use `turbo run build` or `turbo run test` to run tasks across the monorepo efficiently.
+- **Dev Server**: Use `pnpm dev` in specific package or app directories for development.
+
+### UI Development
+
+- Follow existing conventions.
+- Avoid manually importing custom element definitions (these are collected by Root.js during the build process).
+
+### Version Control & Contributions
+
+- **Changesets**: If your changes require a release (version bump), you must create a changeset. Run `pnpm changeset` and follow the prompts.
+- **Commit Messages**: Follow the conventional commit format (e.g., `feat: add new feature`, `fix: resolve issue`).
+- **Linting**: Ensure code passes linting rules by running `pnpm lint`.
+
+### Documentation
+
+- **Comment Style**: All comments MUST end in punctuation. Use block comments to describe interfaces and their fields. Avoid adding superfluous comments. Inline comments MUST also end in punctuation.
+- **Comment Requirements**: When creating new classes, hooks, or components, write at least a brief block comment describing what it is for. For very complex functionality, provide an example of how to use it in the comment.
+
+## Contribution
+
+Refer to `CONTRIBUTING.md` for guidelines on contributing to the project.

.changeset/shiny-cheetahs-hang.md

@@ -0,0 +1,5 @@
+---
+'@blinkk/root-cms': patch
+---
+
+feat: add ai-generated image placeholder feature

AGENTS.md

@@ -1,77 +1 @@
-# Root.js Project Overview
-
-Root.js is a full-featured web development tool with a built-in CMS, designed for building modern, performant websites.
-
-## Key Features
-
-- **TSX Rendering**: Uses TSX for server-side rendering and templating.
-- **Web Components**: Supports standard Web Components for building UI elements.
-- **File Routes**: Intuitive file-based routing system.
-- **i18n**: Built-in support for internationalization.
-- **CMS**: Integrated Content Management System for managing content.
-
-## Project Structure
-
-The project is a monorepo managed with `pnpm` and `turbo`.
-
-### Packages (`packages/`)
-
-- **@blinkk/root** (`packages/root`): The core framework package.
-- **@blinkk/root-cms** (`packages/root-cms`): The CMS integration for Root.js.
-- **@blinkk/create-root** (`packages/create-root`): CLI tool to scaffold new Root.js projects.
-- **Other Packages**:
-  - `eslint-config-root`: Shared ESLint configuration.
-  - `rds`: Likely related to data services or storage (needs verification).
-  - `root-core`: Core logic/utilities.
-  - `root-db`: Database abstraction/layer.
-  - `root-form`: Form handling utilities.
-  - `root-password-protect`: Middleware/utility for password protection.
-  - `root-webui`: UI components or interface for the system.
-
-### Apps (`apps/`)
-
-- **gci**: An application built within the monorepo.
-
-### Documentation (`docs/`)
-
-Contains documentation for the project, likely powering `rootjs.dev`.
-
-### Examples (`examples/`)
-
-Contains example projects demonstrating various features of Root.js.
-
-## Development
-
-- **Package Manager**: `pnpm`
-- **Build System**: `turbo`
-- **Linting**: `eslint`
-
-## Best Practices for Agents
-
-When working on this project, please adhere to the following guidelines:
-
-### Package Management
-
-- **Always use `pnpm`**: This project uses `pnpm` for package management. Do not use `npm` or `yarn`.
-- **Install dependencies**: Run `pnpm install` at the root to install dependencies for all packages.
-
-### Build & Test
-
-- **Use Turbo**: Use `turbo run build` or `turbo run test` to run tasks across the monorepo efficiently.
-- **Dev Server**: Use `pnpm dev` in specific package or app directories for development.
-
-### Version Control & Contributions
-
-- **Changesets**: If your changes require a release (version bump), you must create a changeset. Run `pnpm changeset` and follow the prompts.
-- **Commit Messages**: Follow the conventional commit format (e.g., `feat: add new feature`, `fix: resolve issue`).
-- **Linting**: Ensure code passes linting rules by running `pnpm lint`.
-
-### Documentation
-
-- **Update Docs**: If you change functionality, check if `docs/` needs updating. The documentation is a Root.js app itself.
-- **Comment Style**: All comments should end in punctuation. Use block comments to describe interfaces and their fields. Avoid adding superfluous comments.
-- **Comment Requirements**: When creating new classes, hooks, or components that have medium-to-complex functionality, ensure you write at least a brief block comment describing what it is for. For complex functionality, provide an example of how to use it in the comment.
-
-## Contribution
-
-Refer to `CONTRIBUTING.md` for guidelines on contributing to the project.
+See `.agent/rules/documentation.md` for documentation and rules.

packages/root-cms/core/ai.ts

@@ -94,6 +94,68 @@ export async function summarizeDiff(
   return res.text?.trim() || '';
 }
 
+/** Allowed aspect ratios for image generation (https://docs.cloud.google.com/vertex-ai/generative-ai/docs/reference/rest/v1beta1/GenerationConfig#ImageConfig). */
+export type AspectRatio =
+  | '1:1'
+  | '2:3'
+  | '3:2'
+  | '3:4'
+  | '4:3'
+  | '4:5'
+  | '5:4'
+  | '9:16'
+  | '16:9'
+  | '21:9';
+
+export interface GenerateImageOptions {
+  prompt: string;
+  aspectRatio: AspectRatio;
+}
+
+/**
+ * Generates an image using Vertex AI.
+ */
+export async function generateImage(
+  cmsClient: RootCMSClient,
+  options: GenerateImageOptions
+): Promise<string> {
+  const cmsPluginOptions = cmsClient.cmsPlugin.getConfig();
+  const firebaseConfig = cmsPluginOptions.firebaseConfig;
+  const model = 'vertexai/gemini-2.5-flash-image';
+
+  const ai = genkit({
+    plugins: [
+      vertexAI({
+        projectId: firebaseConfig.projectId,
+        location: firebaseConfig.location || 'us-central1',
+      }),
+    ],
+  });
+
+  const res = await ai.generate({
+    model: model,
+    prompt: [
+      {
+        text: options.prompt,
+      },
+    ],
+    config: {
+      imageConfig: {
+        aspectRatio: options.aspectRatio,
+      },
+    },
+    output: {
+      format: 'media',
+    },
+  });
+
+  if (!res.media) {
+    throw new Error('No image generated');
+  }
+
+  return res.media.url;
+}
+
 export class Chat {
   chatClient: ChatClient;
   cmsClient: RootCMSClient;

packages/root-cms/core/api.ts

@@ -464,4 +464,42 @@ export function api(server: Server, options: ApiOptions) {
       res.status(500).json({success: false, error: 'UNKNOWN'});
     }
   });
+
+  server.use(
+    '/cms/api/ai.generate_image',
+    async (req: Request, res: Response) => {
+      if (
+        req.method !== 'POST' ||
+        !String(req.get('content-type')).startsWith('application/json')
+      ) {
+        res.status(400).json({success: false, error: 'BAD_REQUEST'});
+        return;
+      }
+      if (!req.user?.email) {
+        res.status(401).json({success: false, error: 'UNAUTHORIZED'});
+        return;
+      }
+      const reqBody = req.body || {};
+      const prompt = reqBody.prompt;
+      const aspectRatio = reqBody.aspectRatio;
+
+      if (!prompt || !aspectRatio) {
+        res.status(400).json({success: false, error: 'MISSING_REQUIRED_FIELD'});
+        return;
+      }
+
+      try {
+        const cmsClient = new RootCMSClient(req.rootConfig!);
+        const {generateImage} = await import('./ai.js');
+        const imageUrl = await generateImage(cmsClient, {
+          prompt,
+          aspectRatio,
+        });
+        res.status(200).json({success: true, image: imageUrl});
+      } catch (err: any) {
+        console.error(err.stack || err);
+        res.status(500).json({success: false, error: err.message || 'UNKNOWN'});
+      }
+    }
+  );
 }