@auto-engineer/narrative 1.150.0 → 1.152.0

package/package.json

@@ -26,9 +26,9 @@
     "typescript": "^5.9.2",
     "zod": "^3.22.4",
     "zod-to-json-schema": "^3.22.3",
-    "@auto-engineer/file-store": "1.150.0",
-    "@auto-engineer/id": "1.150.0",
-    "@auto-engineer/message-bus": "1.150.0"
+    "@auto-engineer/id": "1.152.0",
+    "@auto-engineer/message-bus": "1.152.0",
+    "@auto-engineer/file-store": "1.152.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -38,7 +38,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.150.0",
+  "version": "1.152.0",
   "scripts": {
     "build": "tsx scripts/build.ts",
     "test": "vitest run --reporter=dot",

package/src/fluent-builder.specs.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { command, react } from './fluent-builder';
-import { clearCurrentScene, startScene } from './narrative-context';
+import { command, experience, query, react } from './fluent-builder';
+import { clearCurrentScene, getCurrentScene, startScene } from './narrative-context';
 import { createIntegration } from './types';
 
 // Test integrations
@@ -34,3 +34,49 @@ describe('via method', () => {
     expect(slice).toBeDefined();
   });
 });
+
+describe('ui method', () => {
+  beforeEach(() => {
+    startScene('test-flow');
+  });
+
+  afterEach(() => {
+    clearCurrentScene();
+  });
+
+  it('sets client.ui on a command moment', () => {
+    const uiBlock = { layoutId: 'centered-narrow', surface: 'route' as const };
+    command('Submit Order').ui(uiBlock);
+
+    const scene = getCurrentScene();
+    const moment = scene!.moments[0];
+    expect(moment.type).toBe('command');
+    if (moment.type === 'command') {
+      expect(moment.client.ui).toEqual(uiBlock);
+    }
+  });
+
+  it('sets client.ui on a query moment', () => {
+    const uiBlock = { layoutId: 'two-column', surface: 'route' as const };
+    query('View Items').ui(uiBlock);
+
+    const scene = getCurrentScene();
+    const moment = scene!.moments[0];
+    expect(moment.type).toBe('query');
+    if (moment.type === 'query') {
+      expect(moment.client.ui).toEqual(uiBlock);
+    }
+  });
+
+  it('sets client.ui on an experience moment', () => {
+    const uiBlock = { layoutId: 'full-width', surface: 'ephemeral' as const };
+    experience('Welcome Tour').ui(uiBlock);
+
+    const scene = getCurrentScene();
+    const moment = scene!.moments[0];
+    expect(moment.type).toBe('experience');
+    if (moment.type === 'experience') {
+      expect(moment.client.ui).toEqual(uiBlock);
+    }
+  });
+});

package/src/fluent-builder.ts

@@ -1,6 +1,6 @@
 import createDebug from 'debug';
 import { type ASTNode, print } from 'graphql';
-import type { CommandMoment, ExperienceMoment, QueryMoment, ReactMoment } from './index';
+import type { CommandMoment, ExperienceMoment, QueryMoment, ReactMoment, UiBlock } from './index';
 import {
   addMoment,
   endClientBlock,
@@ -38,6 +38,7 @@ export interface FluentCommandMomentBuilder {
   client(description: string, fn: () => void): FluentCommandMomentBuilder;
   server(fn: () => void): FluentCommandMomentBuilder;
   server(description: string, fn: () => void): FluentCommandMomentBuilder;
+  ui(spec: UiBlock): FluentCommandMomentBuilder;
   via(integration: Integration | Integration[]): FluentCommandMomentBuilder;
   retries(count: number): FluentCommandMomentBuilder;
   request(mutation: unknown): FluentCommandMomentBuilder;
@@ -48,6 +49,7 @@ export interface FluentQueryMomentBuilder {
   client(description: string, fn: () => void): FluentQueryMomentBuilder;
   server(fn: () => void): FluentQueryMomentBuilder;
   server(description: string, fn: () => void): FluentQueryMomentBuilder;
+  ui(spec: UiBlock): FluentQueryMomentBuilder;
   request(query: unknown): FluentQueryMomentBuilder;
 }
 
@@ -61,6 +63,7 @@ export interface FluentReactionMomentBuilder {
 export interface FluentExperienceMomentBuilder {
   client(fn: () => void): FluentExperienceMomentBuilder;
   client(description: string, fn: () => void): FluentExperienceMomentBuilder;
+  ui(spec: UiBlock): FluentExperienceMomentBuilder;
 }
 
 class CommandMomentBuilderImpl implements FluentCommandMomentBuilder {
@@ -132,6 +135,12 @@ class CommandMomentBuilderImpl implements FluentCommandMomentBuilder {
     return this;
   }
 
+  ui(spec: UiBlock): FluentCommandMomentBuilder {
+    debugCommand('Setting client.ui for moment %s', this.moment.name);
+    this.moment.client.ui = spec;
+    return this;
+  }
+
   via(integration: Integration | Integration[]): FluentCommandMomentBuilder {
     const integrations = Array.isArray(integration) ? integration : [integration];
     this.moment.via = integrations.map((i) => i.name);
@@ -232,6 +241,12 @@ class QueryMomentBuilderImpl implements FluentQueryMomentBuilder {
     return this;
   }
 
+  ui(spec: UiBlock): FluentQueryMomentBuilder {
+    debugQuery('Setting client.ui for moment %s', this.moment.name);
+    this.moment.client.ui = spec;
+    return this;
+  }
+
   request(query: unknown): FluentQueryMomentBuilder {
     debugQuery('Setting request for moment %s', this.moment.name);
     if (typeof query === 'string') {
@@ -346,6 +361,12 @@ class ExperienceMomentBuilderImpl implements FluentExperienceMomentBuilder {
 
     return this;
   }
+
+  ui(spec: UiBlock): FluentExperienceMomentBuilder {
+    debugExperience('Setting client.ui for moment %s', this.moment.name);
+    this.moment.client.ui = spec;
+    return this;
+  }
 }
 
 export const command = (name: string, id?: string): FluentCommandMomentBuilder => {

package/src/model-to-narrative.specs.ts

@@ -3569,4 +3569,42 @@ scene('All Projection Types', 'ALL-PROJ', () => {
     expect(code).toContain("type FitnessGoalCreated = Event<'FitnessGoalCreated'");
     expect(code).toContain("type FitnessGoalsView = State<'FitnessGoalsView'");
   });
+
+  it('emits .ui() when moment has client.ui', async () => {
+    const model: Model = {
+      variant: 'specs',
+      scenes: [
+        {
+          name: 'Checkout',
+          moments: [
+            {
+              type: 'command',
+              name: 'Submit Order',
+              client: {
+                specs: [],
+                ui: {
+                  layoutId: 'centered-narrow',
+                  surface: 'route',
+                  spec: { root: 'layout-root', elements: {}, state: {} },
+                },
+              },
+              server: { description: '', specs: [] },
+            },
+          ],
+        },
+      ],
+      messages: [],
+      integrations: [],
+      modules: [],
+      narratives: [],
+    };
+
+    const result = await modelToNarrative(model);
+    const code = getCode(result);
+
+    expect(code).toContain('.ui(');
+    expect(code).toContain("layoutId: 'centered-narrow'");
+    expect(code).toContain("surface: 'route'");
+    expect(code).toContain("root: 'layout-root'");
+  });
 });

package/src/schema.specs.ts

@@ -57,6 +57,39 @@ describe('CommandMomentSchema', () => {
   });
 });
 
+describe('CommandMomentSchema client.ui', () => {
+  it('accepts ui block in client alongside specs', () => {
+    const moment = {
+      type: 'command' as const,
+      name: 'Submit Order',
+      client: {
+        specs: [],
+        ui: {
+          layoutId: 'centered-narrow',
+          mode: 'as-is',
+          regions: { main: [{ id: 'r1', name: 'hero' }] },
+          spec: { root: 'layout-root', elements: {}, state: {} },
+          surface: 'route',
+        },
+      },
+      server: { description: 'Submits order', specs: [] },
+    };
+
+    const result = CommandMomentSchema.safeParse(moment);
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.client.ui).toEqual({
+        layoutId: 'centered-narrow',
+        mode: 'as-is',
+        regions: { main: [{ id: 'r1', name: 'hero' }] },
+        spec: { root: 'layout-root', elements: {}, state: {} },
+        surface: 'route',
+      });
+    }
+  });
+});
+
 describe('SceneRouteSchema', () => {
   it('should accept valid route types', () => {
     for (const type of ['dedicated', 'nested', 'no-route'] as const) {

package/src/schema.ts

@@ -351,10 +351,24 @@ export const ClientSpecNodeSchema: z.ZodType<ClientSpecNode> = z.lazy(() =>
 
 export const ClientSpecSchema = z.array(ClientSpecNodeSchema).default([]);
 
+export const UiBlockSchema = z
+  .object({
+    layoutId: z.string().optional().describe('Layout template identifier'),
+    mode: z.string().optional().describe('Rendering mode'),
+    regions: z
+      .record(z.array(z.object({ id: z.string(), name: z.string(), slots: z.record(z.unknown()).optional() })))
+      .optional()
+      .describe('Layout regions with placed components'),
+    spec: z.record(z.unknown()).optional().describe('UI specification tree'),
+    surface: z.enum(['route', 'overlay', 'ephemeral']).optional().describe('Presentation context'),
+  })
+  .describe('UI composition block for a moment');
+
 const CommandMomentSchema = BaseMomentSchema.extend({
   type: z.literal('command'),
   client: z.object({
     specs: ClientSpecSchema,
+    ui: UiBlockSchema.optional().describe('UI composition for this moment'),
   }),
   request: z.string().describe('Command request (GraphQL, REST endpoint, or other query format)').optional(),
   mappings: z.array(MappingEntrySchema).optional().describe('Field mappings between Command/Event/State messages'),
@@ -369,6 +383,7 @@ const QueryMomentSchema = BaseMomentSchema.extend({
   type: z.literal('query'),
   client: z.object({
     specs: ClientSpecSchema,
+    ui: UiBlockSchema.optional().describe('UI composition for this moment'),
   }),
   request: z.string().describe('Query request (GraphQL, REST endpoint, or other query format)').optional(),
   mappings: z.array(MappingEntrySchema).optional().describe('Field mappings between Command/Event/State messages'),
@@ -392,6 +407,7 @@ const ExperienceMomentSchema = BaseMomentSchema.extend({
   type: z.literal('experience'),
   client: z.object({
     specs: ClientSpecSchema,
+    ui: UiBlockSchema.optional().describe('UI composition for this moment'),
   }),
 }).describe('Experience moment for user interactions and UI behavior');
 
@@ -628,3 +644,4 @@ export type UIElement = z.infer<typeof UIElementSchema>;
 export type UISpec = z.infer<typeof UISpecSchema>;
 export type UI = z.infer<typeof UISchema>;
 export type ComponentDefinition = z.infer<typeof ComponentDefinitionSchema>;
+export type UiBlock = z.infer<typeof UiBlockSchema>;

package/src/transformers/model-to-narrative/generators/flow.ts

@@ -424,6 +424,20 @@ function addClientToChain(
   return chain;
 }
 
+function addUiToChain(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  chain: tsNS.Expression,
+  slice: Moment,
+): tsNS.Expression {
+  if ('client' in slice && slice.client?.ui !== undefined) {
+    return f.createCallExpression(f.createPropertyAccessExpression(chain, f.createIdentifier('ui')), undefined, [
+      jsonToExpr(ts, f, slice.client.ui),
+    ]);
+  }
+  return chain;
+}
+
 function addRequestToChain(
   f: tsNS.NodeFactory,
   chain: tsNS.Expression,
@@ -767,6 +781,7 @@ function buildMoment(
   let chain: tsNS.Expression = f.createCallExpression(f.createIdentifier(sliceCtor), undefined, args);
 
   chain = addClientToChain(ts, f, chain, slice);
+  chain = addUiToChain(ts, f, chain, slice);
   chain = addRequestToChain(f, chain, slice);
   chain = addServerToChain(ts, f, chain, slice, messages);