@positronic/template-new-project 0.0.52 → 0.0.53

package/index.js

@@ -53,9 +53,10 @@ module.exports = {
   ],
   setup: async ctx => {
     const devRootPath = process.env.POSITRONIC_LOCAL_PATH;
-    let coreVersion = '^0.0.52';
-    let cloudflareVersion = '^0.0.52';
-    let clientVercelVersion = '^0.0.52';
+    let coreVersion = '^0.0.53';
+    let cloudflareVersion = '^0.0.53';
+    let clientVercelVersion = '^0.0.53';
+    let genUIComponentsVersion = '^0.0.53';
 
     // Map backend selection to package names
     const backendPackageMap = {
@@ -98,6 +99,12 @@ module.exports = {
       if (existsSync(clientVercelPath)) {
         clientVercelVersion = `file:${clientVercelPath}`;
       }
+
+      const genUIComponentsPath = path.resolve(devRootPath, 'packages', 'gen-ui-components');
+      if (existsSync(genUIComponentsPath)) {
+        genUIComponentsVersion = `file:${genUIComponentsPath}`;
+        console.log(`  - Mapping @positronic/gen-ui-components to ${genUIComponentsVersion}`);
+      }
     }
 
     ctx.answers.positronicCoreVersion = coreVersion;
@@ -106,6 +113,7 @@ module.exports = {
     }
 
     ctx.answers.positronicClientVercelVersion = clientVercelVersion;
+    ctx.answers.positronicGenUIComponentsVersion = genUIComponentsVersion;
 
     if (ctx.answers.install) {
       const pm = ctx.answers.pm;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@positronic/template-new-project",
-  "version": "0.0.52",
+  "version": "0.0.53",
   "publishConfig": {
     "access": "public"
   },

package/template/brain.ts

@@ -1,72 +1,63 @@
-import { brain as coreBrain, type BrainFactory } from '@positronic/core';
+import { createBrain } from '@positronic/core';
+import { components } from './components/index.js';
 
 /**
- * Base brain factory for this project.
- * 
- * This wrapper allows you to configure services once and have them available
- * in all brains throughout your project.
- * 
- * To add services:
- * 1. Define your service interfaces
- * 2. Create service instances
- * 3. Call .withServices() on the brain before returning it
- * 
- * Example with services:
+ * Project-level brain function with pre-configured components.
+ *
+ * All brains in your project should import from this file:
+ *
  * ```typescript
- * interface ProjectServices {
- *   logger: {
- *     info: (message: string) => void;
- *     error: (message: string) => void;
- *   };
- *   api: {
- *     fetch: (endpoint: string) => Promise<any>;
- *   };
- * }
- * 
- * export const brain: BrainFactory = (brainConfig) => {
- *   return coreBrain(brainConfig)
- *     .withServices({
- *       logger: {
- *         info: (msg) => console.log(`[INFO] <%= '${msg}' %>`),
- *         error: (msg) => console.error(`[ERROR] <%= '${msg}' %>`)
- *       },
- *       api: {
- *         fetch: async (endpoint) => {
- *           const response = await fetch(`https://api.example.com<%= '${endpoint}' %>`);
- *           return response.json();
- *         }
- *       }
- *     });
- * }
+ * import { brain } from '../brain.js';
+ *
+ * export default brain('my-brain')
+ *   .step('Do something', ({ state }) => ({ ...state, done: true }));
  * ```
- * 
- * Then in your brain files (in the brains/ directory):
+ *
+ * To add services (e.g., Slack, Gmail, database clients):
+ *
  * ```typescript
- * import { brain } from '../brain.js';
- * import { z } from 'zod';
- * 
- * const optionsSchema = z.object({
- *   environment: z.string().default('prod'),
- *   verbose: z.string().default('false')
+ * import { createBrain } from '@positronic/core';
+ * import { components } from './components/index.js';
+ * import slack from './services/slack.js';
+ * import gmail from './services/gmail.js';
+ *
+ * export const brain = createBrain({
+ *   services: { slack, gmail },
+ *   components,
  * });
- * 
- * export default brain('My Brain')
- *   .withOptionsSchema(optionsSchema)
- *   .step('Use Services', async ({ state, options, logger, api }) => {
- *     if (options.verbose === 'true') {
- *       logger.info('Fetching data...');
- *     }
- *     const endpoint = options.environment === 'dev' ? '/users/test' : '/users';
- *     const data = await api.fetch(endpoint);
- *     return { users: data };
+ * ```
+ *
+ * Then services are available in all brain steps:
+ *
+ * ```typescript
+ * export default brain('notify')
+ *   .step('Send alert', ({ slack }) => {
+ *     slack.postMessage('#alerts', 'Something happened!');
+ *     return { notified: true };
  *   });
  * ```
- * 
- * Run with custom options from CLI:
- * px brain run my-brain -o environment=dev -o verbose=true
+ *
+ * You can also create agents directly:
+ *
+ * ```typescript
+ * export default brain('my-agent', ({ slack, env }) => ({
+ *   system: 'You are a helpful assistant',
+ *   prompt: 'Help the user with their request',
+ *   tools: {
+ *     notify: {
+ *       description: 'Send a Slack notification',
+ *       inputSchema: z.object({ message: z.string() }),
+ *       execute: ({ message }) => slack.postMessage('#general', message),
+ *     },
+ *     done: {
+ *       description: 'Complete the task',
+ *       inputSchema: z.object({ result: z.string() }),
+ *       terminal: true,
+ *     },
+ *   },
+ * }));
+ * ```
  */
-export const brain: BrainFactory = (brainConfig) => {
-  // For now, just return the core brain without any services.
-  // Update this function to add your project-wide services.
-  return coreBrain(brainConfig);
-};
+export const brain = createBrain({
+  components,
+});

package/template/components/bundle.ts

@@ -0,0 +1,23 @@
+/**
+ * Bundle entry point for client-side rendering.
+ *
+ * This file is bundled by esbuild into dist/components.js which exposes
+ * React components to window.PositronicComponents for use by generated pages.
+ *
+ * When you add custom components to ./index.ts, they will automatically
+ * be included in the bundle.
+ */
+import { components } from './index.js';
+
+// Extract the React component from each UIComponent and expose to window
+const PositronicComponents: Record<string, React.ComponentType<any>> = {};
+
+for (const [name, uiComponent] of Object.entries(components)) {
+  PositronicComponents[name] = uiComponent.component;
+}
+
+// Expose to window for client-side rendering
+(window as unknown as { PositronicComponents: typeof PositronicComponents }).PositronicComponents =
+  PositronicComponents;
+
+export { PositronicComponents };

package/template/components/index.ts

@@ -0,0 +1,26 @@
+/**
+ * UI Components for this project.
+ *
+ * This file re-exports the default Positronic components and is the place
+ * to add your own custom components.
+ *
+ * To add a custom component:
+ * 1. Create a component file (e.g., CustomButton.ts) with UIComponent structure
+ * 2. Import and add it to the components object below
+ *
+ * @example
+ * ```typescript
+ * import { CustomButton } from './CustomButton.js';
+ *
+ * export const components = {
+ *   ...defaultComponents,
+ *   CustomButton,
+ * };
+ * ```
+ */
+import { components as defaultComponents } from '@positronic/gen-ui-components';
+
+// Re-export default components - add your custom components here
+export const components = {
+  ...defaultComponents,
+};

package/template/docs/brain-dsl-guide.md

@@ -678,6 +678,163 @@ Extract prompts to separate files when:
 - The prompt might be reused in other brains
 - You want to test the prompt logic separately
 
+## UI Steps
+
+UI steps allow brains to generate dynamic user interfaces using AI. The `.ui()` step generates a page and provides a `page` object to the next step. You then notify users and use `waitFor` to pause until the form is submitted.
+
+### Basic UI Step
+
+```typescript
+import { z } from 'zod';
+
+brain('Feedback Collector')
+  .step('Initialize', ({ state }) => ({
+    ...state,
+    userName: 'John Doe',
+  }))
+  // Generate the form
+  .ui('Collect Feedback', {
+    template: (state) => `
+      Create a feedback form for <%= '${state.userName}' %>.
+      Include fields for rating (1-5) and comments.
+    `,
+    responseSchema: z.object({
+      rating: z.number().min(1).max(5),
+      comments: z.string(),
+    }),
+  })
+  // Notify user and wait for submission
+  .step('Notify and Wait', async ({ state, page, slack }) => {
+    await slack.post('#feedback', `Please fill out: <%= '${page.url}' %>`);
+    return {
+      state,
+      waitFor: [page.webhook],
+    };
+  })
+  // Process the form data (comes through response, not page)
+  .step('Process Feedback', ({ state, response }) => ({
+    ...state,
+    feedbackReceived: true,
+    rating: response.rating,     // typed from responseSchema
+    comments: response.comments,
+  }));
+```
+
+### How UI Steps Work
+
+1. **Template**: The `template` function generates a prompt describing the desired UI
+2. **AI Generation**: The AI creates a component tree based on the prompt
+3. **Page Object**: Next step receives `page` with `url` and `webhook`
+4. **Notification**: You notify users however you want (Slack, email, etc.)
+5. **Wait**: Use `waitFor: [page.webhook]` to pause until form submission
+6. **Form Data**: Step after `waitFor` receives form data via `response`
+
+### The `page` Object
+
+After a `.ui()` step, the next step receives:
+- `page.url` - URL where users can access the form
+- `page.webhook` - Pre-configured webhook for form submissions
+
+### Template Best Practices
+
+Be specific about layout and content:
+
+```typescript
+.ui('Contact Form', {
+  template: (state) => `
+    Create a contact form with:
+    - Header: "Get in Touch"
+    - Name field (required)
+    - Email field (required, pre-filled with "<%= '${state.email}' %>")
+    - Message textarea (required)
+    - Submit button labeled "Send Message"
+
+    Use a clean, centered single-column layout.
+  `,
+  responseSchema: z.object({
+    name: z.string(),
+    email: z.string().email(),
+    message: z.string(),
+  }),
+})
+```
+
+### Data Bindings
+
+Use `{{path}}` syntax to bind props to runtime data:
+
+```typescript
+.ui('Order Summary', {
+  template: (state) => `
+    Create an order summary showing:
+    - List of items from {{cart.items}}
+    - Total: {{cart.total}}
+    - Shipping address input
+    - Confirm button
+  `,
+  responseSchema: z.object({
+    shippingAddress: z.string(),
+  }),
+})
+```
+
+### Multi-Step Forms
+
+Chain UI steps for multi-page workflows:
+
+```typescript
+brain('User Onboarding')
+  .step('Start', () => ({ userData: {} }))
+
+  // Step 1: Personal info
+  .ui('Personal Info', {
+    template: () => `
+      Create a form for personal information:
+      - First name, Last name
+      - Date of birth
+      - Next button
+    `,
+    responseSchema: z.object({
+      firstName: z.string(),
+      lastName: z.string(),
+      dob: z.string(),
+    }),
+  })
+  .step('Wait for Personal', async ({ state, page, notify }) => {
+    await notify(`Step 1: <%= '${page.url}' %>`);
+    return { state, waitFor: [page.webhook] };
+  })
+  .step('Save Personal', ({ state, response }) => ({
+    ...state,
+    userData: { ...state.userData, ...response },
+  }))
+
+  // Step 2: Preferences
+  .ui('Preferences', {
+    template: (state) => `
+      Create preferences form for <%= '${state.userData.firstName}' %>:
+      - Newsletter subscription checkbox
+      - Contact preference (email/phone/sms)
+      - Complete button
+    `,
+    responseSchema: z.object({
+      newsletter: z.boolean(),
+      contactMethod: z.enum(['email', 'phone', 'sms']),
+    }),
+  })
+  .step('Wait for Preferences', async ({ state, page, notify }) => {
+    await notify(`Step 2: <%= '${page.url}' %>`);
+    return { state, waitFor: [page.webhook] };
+  })
+  .step('Complete', ({ state, response }) => ({
+    ...state,
+    userData: { ...state.userData, preferences: response },
+    onboardingComplete: true,
+  }));
+```
+
+For more details on UI steps, see the full UI Step Guide in the main Positronic documentation.
+
 ## Complete Example
 
 ```typescript
@@ -722,14 +879,9 @@ const completeBrain = brain({
       }),
       name: 'plan' as const,
     },
-  },
-  // Services available in reduce function too
-  ({ state, response, logger }) => {
-    logger.log(`Plan generated with <%= '${response.tasks.length}' %> tasks`);
-    return { ...state, plan: response };
   })
   .step('Process Plan', ({ state, logger, analytics }) => {
-    logger.log(`Processing <%= '${state.plan.tasks.length}' %> tasks`);
+    logger.log(`Plan generated with <%= '${state.plan.tasks.length}' %> tasks`);
     analytics.track('plan_processed', {
       task_count: state.plan.tasks.length,
       duration: state.plan.duration

package/template/docs/positronic-guide.md

@@ -239,5 +239,5 @@ const api = {
 
 - **Documentation**: https://positronic.dev
 - **CLI Help**: `px --help`
-- **Brain DSL Guide**: `/docs/brain-dsl-guide.md`
+- **Brain DSL Guide**: `/docs/brain-dsl-guide.md` (includes UI steps for generating forms)
 - **Testing Guide**: `/docs/brain-testing-guide.md`

package/template/docs/tips-for-agents.md

@@ -182,6 +182,56 @@ brain('validation-example')
 
 Most generated brains should not have try-catch blocks. Only use them when the error state is meaningful to subsequent steps in the workflow.
 
+## UI Steps for Form Generation
+
+When you need to collect user input, use the `.ui()` method. The pattern is:
+1. `.ui()` generates the page
+2. Next step gets `page.url` and `page.webhook`
+3. Notify users and use `waitFor: [page.webhook]`
+4. Step after `waitFor` gets form data in `response`
+
+```typescript
+import { z } from 'zod';
+
+brain('feedback-collector')
+  .step('Initialize', ({ state }) => ({
+    ...state,
+    userName: 'John',
+  }))
+  // Generate the form
+  .ui('Collect Feedback', {
+    template: (state) => <%= '\`' %>
+      Create a feedback form for <%= '${state.userName}' %>:
+      - Rating (1-5)
+      - Comments textarea
+      - Submit button
+    <%= '\`' %>,
+    responseSchema: z.object({
+      rating: z.number().min(1).max(5),
+      comments: z.string(),
+    }),
+  })
+  // Notify and wait for submission
+  .step('Notify', async ({ state, page, slack }) => {
+    await slack.post('#feedback', `Fill out: <%= '${page.url}' %>`);
+    return { state, waitFor: [page.webhook] };
+  })
+  // Form data comes through response (not page)
+  .step('Process', ({ state, response }) => ({
+    ...state,
+    rating: response.rating,     // Typed from responseSchema
+    comments: response.comments,
+  }));
+```
+
+Key points:
+- `page.url` - where to send users
+- `page.webhook` - use with `waitFor` to pause for submission
+- `response` - form data arrives here (in step after `waitFor`)
+- You control how users are notified (Slack, email, etc.)
+
+See `/docs/brain-dsl-guide.md` for more UI step examples.
+
 ## Service Organization
 
 When implementing services for the project brain, consider creating a `services/` directory at the root of your project to keep service implementations organized and reusable:

package/template/esbuild.config.mjs

@@ -0,0 +1,26 @@
+/**
+ * esbuild configuration for bundling UI components.
+ *
+ * This bundles the components from ./components/bundle.ts into a single
+ * JavaScript file that can be served to the browser.
+ *
+ * Run: npm run build:components
+ * Or let the dev server build it automatically.
+ */
+import * as esbuild from 'esbuild';
+
+await esbuild.build({
+  entryPoints: ['components/bundle.ts'],
+  bundle: true,
+  external: ['react', 'react-dom'],
+  format: 'iife',
+  outfile: 'dist/components.js',
+  jsx: 'transform',
+  jsxFactory: 'React.createElement',
+  jsxFragment: 'React.Fragment',
+  tsconfigRaw: {
+    compilerOptions: {
+      jsx: 'react',
+    },
+  },
+});

package/template/package.json

@@ -6,7 +6,8 @@
   "type": "module",
   "scripts": {
     "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "build:components": "node esbuild.config.mjs"
   },
   "keywords": [],
   "author": "",
@@ -15,15 +16,18 @@
     "zod": "^3.24.1",
     "@positronic/client-vercel": "<%= positronicClientVercelVersion %>",
     "@ai-sdk/openai": "^1.3.22",
-    "@positronic/core": "<%= positronicCoreVersion %>"<% if (backend === 'cloudflare') { %>,
+    "@positronic/core": "<%= positronicCoreVersion %>",
+    "@positronic/gen-ui-components": "<%= positronicGenUIComponentsVersion %>"<% if (backend === 'cloudflare') { %>,
     "@positronic/cloudflare": "<%= positronicCloudflareVersion %>"<% } %>
   },
   "devDependencies": {<% if (backend === 'cloudflare') { %>
-    "wrangler": "^4.0.0",<% } %>
+    "wrangler": "^4.37.0",<% } %>
     "typescript": "^5.0.0",
     "jest": "^30.0.4",
     "@jest/globals": "^30.0.4",
     "ts-jest": "^29.2.6",
-    "@types/jest": "^30.0.0"
+    "@types/jest": "^30.0.0",
+    "esbuild": "^0.24.0",
+    "@types/react": "^18.2.0"
   }
 }

package/template/tests/test-utils.ts

@@ -19,8 +19,13 @@ export function createMockClient(): MockClient {
     return responses[responseIndex++];
   });
 
+  const streamText = jest.fn(async () => {
+    throw new Error('streamText not implemented in mock');
+  });
+
   return {
     generateObject,
+    streamText,
     mockResponses: (...newResponses: any[]) => {
       responses.push(...newResponses);
     },
@@ -28,6 +33,7 @@ export function createMockClient(): MockClient {
       responses.length = 0;
       responseIndex = 0;
       generateObject.mockClear();
+      streamText.mockClear();
     },
   };
 }