@auto-engineer/narrative 1.144.0 → 1.145.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.144.0",
-    "@auto-engineer/id": "1.144.0",
-    "@auto-engineer/message-bus": "1.144.0"
+    "@auto-engineer/file-store": "1.145.0",
+    "@auto-engineer/id": "1.145.0",
+    "@auto-engineer/message-bus": "1.145.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -38,7 +38,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.144.0",
+  "version": "1.145.0",
   "scripts": {
     "build": "tsx scripts/build.ts",
     "test": "vitest run --reporter=dot",

package/src/schema.specs.ts

@@ -3,10 +3,11 @@ import type {
   ComponentDefinition,
   Narrative,
   NarrativePlanning,
-  RegionEntry,
   SceneClassification,
   SceneRoute,
   UI,
+  UIElement,
+  UISpec,
 } from './schema';
 import {
   CommandMomentSchema,
@@ -18,12 +19,13 @@ import {
   NarrativePlanningSchema,
   NarrativeSchema,
   QueryMomentSchema,
-  RegionEntrySchema,
   SceneClassificationSchema,
   SceneNamesOnlySchema,
   SceneRouteSchema,
   SceneSchema,
+  UIElementSchema,
   UISchema,
+  UISpecSchema,
 } from './schema';
 
 describe('CommandMomentSchema', () => {
@@ -547,89 +549,70 @@ describe('QueryMomentSchema', () => {
   });
 });
 
-describe('RegionEntrySchema', () => {
-  it('should accept valid region entry with required fields', () => {
-    const result = RegionEntrySchema.safeParse({ id: 'hero-1', name: 'HeroBanner' });
+describe('UIElementSchema', () => {
+  it('should accept a minimal element with type only', () => {
+    const result = UIElementSchema.safeParse({ type: 'Stack' });
     expect(result.success).toBe(true);
-    if (result.success) {
-      expect(result.data).toEqual({ id: 'hero-1', name: 'HeroBanner' });
-    }
-  });
-
-  it('should accept optional slots', () => {
-    const result = RegionEntrySchema.safeParse({ id: 'card-1', name: 'Card', slots: { title: 'Hello' } });
-    expect(result.success).toBe(true);
-    if (result.success) {
-      expect(result.data.slots).toEqual({ title: 'Hello' });
-    }
   });
 
-  it('should reject missing id', () => {
-    const result = RegionEntrySchema.safeParse({ name: 'Card' });
-    expect(result.success).toBe(false);
+  it('should accept an element with all fields', () => {
+    const element = {
+      type: 'Heading',
+      props: { text: { $state: '/title' }, level: 'h1' },
+      children: ['subtitle'],
+      visible: { $state: '/showTitle' },
+      repeat: { statePath: '/items', key: 'id' },
+      watch: { '/count': { action: 'refresh' } },
+    };
+    expect(UIElementSchema.parse(element)).toEqual(element);
   });
 
-  it('should reject missing name', () => {
-    const result = RegionEntrySchema.safeParse({ id: 'card-1' });
-    expect(result.success).toBe(false);
+  it('should accept repeat with object statePath for nested repeats', () => {
+    const element = {
+      type: 'Stack',
+      children: [],
+      repeat: { statePath: { $item: 'fields' }, key: 'name' },
+    };
+    expect(UIElementSchema.parse(element)).toEqual(element);
   });
 });
 
-describe('UISchema', () => {
-  it('should accept valid UI with required fields', () => {
-    const result = UISchema.safeParse({
-      layoutId: 'two-column',
-      mode: 'as-is',
-      regions: { main: [{ id: 'c-1', name: 'List' }] },
-    });
-    expect(result.success).toBe(true);
-    if (result.success) {
-      expect(result.data).toEqual({
-        layoutId: 'two-column',
-        mode: 'as-is',
-        regions: { main: [{ id: 'c-1', name: 'List' }] },
-      });
-    }
-  });
-
-  it('should accept all valid mode values', () => {
-    for (const mode of ['as-is', 'modify', 'custom'] as const) {
-      const result = UISchema.safeParse({ layoutId: 'l', mode, regions: {} });
-      expect(result.success).toBe(true);
-    }
-  });
-
-  it('should reject invalid mode', () => {
-    const result = UISchema.safeParse({ layoutId: 'l', mode: 'invalid', regions: {} });
-    expect(result.success).toBe(false);
+describe('UISpecSchema', () => {
+  it('should accept a valid spec with root, elements, and state', () => {
+    const spec = {
+      root: 'page',
+      elements: {
+        page: { type: 'Stack', props: { direction: 'vertical' }, children: ['heading'] },
+        heading: { type: 'Heading', props: { text: 'Hello' }, children: [] },
+      },
+      state: { title: 'Hello' },
+    };
+    expect(UISpecSchema.parse(spec)).toEqual(spec);
   });
 
-  it('should accept optional customizationNotes', () => {
-    const result = UISchema.safeParse({
-      layoutId: 'l',
-      mode: 'modify',
-      regions: {},
-      customizationNotes: 'Make header sticky',
-    });
-    expect(result.success).toBe(true);
-    if (result.success) {
-      expect(result.data.customizationNotes).toBe('Make header sticky');
-    }
+  it('should reject a spec missing root', () => {
+    expect(UISpecSchema.safeParse({ elements: {} }).success).toBe(false);
   });
 
-  it('should reject missing layoutId', () => {
-    const result = UISchema.safeParse({ mode: 'as-is', regions: {} });
-    expect(result.success).toBe(false);
+  it('should reject a spec missing elements', () => {
+    expect(UISpecSchema.safeParse({ root: 'x' }).success).toBe(false);
   });
+});
 
-  it('should reject missing mode', () => {
-    const result = UISchema.safeParse({ layoutId: 'l', regions: {} });
-    expect(result.success).toBe(false);
+describe('UISchema', () => {
+  it('should accept an empty object since spec is optional', () => {
+    expect(UISchema.parse({})).toEqual({});
   });
 
-  it('should reject missing regions', () => {
-    const result = UISchema.safeParse({ layoutId: 'l', mode: 'as-is' });
-    expect(result.success).toBe(false);
+  it('should accept a UI with a spec', () => {
+    const ui = {
+      spec: {
+        root: 'page',
+        elements: { page: { type: 'Stack', children: [] } },
+        state: { title: 'Dashboard' },
+      },
+    };
+    expect(UISchema.parse(ui)).toEqual(ui);
   });
 });
 
@@ -663,26 +646,21 @@ describe('ComponentDefinitionSchema', () => {
 });
 
 describe('DesignSchema ui field', () => {
-  it('should accept design with optional ui', () => {
-    const result = DesignSchema.safeParse({
+  it('should accept design with ui containing a spec', () => {
+    const design = {
       ui: {
-        layoutId: 'sidebar',
-        mode: 'as-is',
-        regions: { sidebar: [{ id: 'nav', name: 'NavMenu' }] },
+        spec: {
+          root: 'page',
+          elements: { page: { type: 'Stack', children: [] } },
+          state: { title: 'Dashboard' },
+        },
       },
-    });
-    expect(result.success).toBe(true);
-    if (result.success) {
-      expect(result.data.ui?.layoutId).toBe('sidebar');
-    }
+    };
+    expect(DesignSchema.parse(design)).toEqual(design);
   });
 
   it('should accept design without ui', () => {
-    const result = DesignSchema.safeParse({});
-    expect(result.success).toBe(true);
-    if (result.success) {
-      expect(result.data.ui).toBeUndefined();
-    }
+    expect(DesignSchema.parse({})).toEqual({});
   });
 });
 
@@ -731,16 +709,23 @@ describe('modelSchema design.components field', () => {
 });
 
 describe('exported UI types', () => {
-  it('RegionEntry type matches RegionEntrySchema inference', () => {
-    const parsed = RegionEntrySchema.parse({ id: 'r-1', name: 'Header' });
-    const typed: RegionEntry = parsed;
-    expect(typed).toEqual({ id: 'r-1', name: 'Header' });
+  it('UIElement type matches UIElementSchema inference', () => {
+    const parsed = UIElementSchema.parse({ type: 'Stack', children: [] });
+    const typed: UIElement = parsed;
+    expect(typed).toEqual({ type: 'Stack', children: [] });
+  });
+
+  it('UISpec type matches UISpecSchema inference', () => {
+    const spec = { root: 'page', elements: { page: { type: 'Stack', children: [] } } };
+    const parsed = UISpecSchema.parse(spec);
+    const typed: UISpec = parsed;
+    expect(typed).toEqual(spec);
   });
 
   it('UI type matches UISchema inference', () => {
-    const parsed = UISchema.parse({ layoutId: 'l', mode: 'as-is', regions: {} });
+    const parsed = UISchema.parse({});
     const typed: UI = parsed;
-    expect(typed).toEqual({ layoutId: 'l', mode: 'as-is', regions: {} });
+    expect(typed).toEqual({});
   });
 
   it('ComponentDefinition type matches ComponentDefinitionSchema inference', () => {
@@ -753,6 +738,6 @@ describe('exported UI types', () => {
       template: '<button/>',
     });
     const typed: ComponentDefinition = parsed;
-    expect(typed.name).toBe('Btn');
+    expect(typed).toEqual(parsed);
   });
 });

package/src/schema.ts

@@ -218,20 +218,32 @@ export const ImageAssetSchema = z
   })
   .describe('Image asset with optional generation metadata');
 
-const RegionEntrySchema = z
+export const UIElementSchema = z
+  .object({
+    type: z.string(),
+    props: z.record(z.unknown()).optional(),
+    children: z.array(z.string()).optional(),
+    visible: z.unknown().optional(),
+    repeat: z
+      .object({ statePath: z.union([z.string(), z.record(z.unknown())]) })
+      .passthrough()
+      .optional(),
+    watch: z.record(z.unknown()).optional(),
+  })
+  .passthrough()
+  .describe('Single UI element in a UI spec');
+
+export const UISpecSchema = z
   .object({
-    id: z.string(),
-    name: z.string(),
-    slots: z.record(z.unknown()).optional(),
+    root: z.string(),
+    elements: z.record(UIElementSchema),
+    state: z.record(z.unknown()).optional(),
   })
-  .describe('Component placed in a layout region');
+  .describe('Flat element-map UI specification');
 
 const UISchema = z
   .object({
-    layoutId: z.string(),
-    mode: z.enum(['as-is', 'modify', 'custom']),
-    regions: z.record(z.array(RegionEntrySchema)),
-    customizationNotes: z.string().optional(),
+    spec: UISpecSchema.optional().describe('The rendered UI spec — source of truth for rendering'),
   })
   .describe('UI composition for a moment');
 
@@ -584,7 +596,6 @@ export {
   StepErrorSchema,
   StepWithDocStringSchema,
   StepWithErrorSchema,
-  RegionEntrySchema,
   UISchema,
   ComponentDefinitionSchema,
 };
@@ -613,6 +624,7 @@ export type SceneRoute = z.infer<typeof SceneRouteSchema>;
 export type NarrativePlanning = z.infer<typeof NarrativePlanningSchema>;
 export type ImageAsset = z.infer<typeof ImageAssetSchema>;
 export type Design = z.infer<typeof DesignSchema>;
-export type RegionEntry = z.infer<typeof RegionEntrySchema>;
+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>;