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

package/src/schema.specs.ts

@@ -1,17 +1,29 @@
 import { describe, expect, it } from 'vitest';
-import type { Journey, JourneyPlanning, SceneClassification, SceneRoute } from './schema';
+import type {
+  ComponentDefinition,
+  Journey,
+  JourneyPlanning,
+  RegionEntry,
+  SceneClassification,
+  SceneRoute,
+  UI,
+} from './schema';
 import {
   CommandSliceSchema,
+  ComponentDefinitionSchema,
   DataSchema,
   DataTargetSchema,
+  DesignSchema,
   JourneyPlanningSchema,
   JourneySchema,
   modelSchema,
   NarrativeNamesOnlySchema,
   NarrativeSchema,
   QuerySliceSchema,
+  RegionEntrySchema,
   SceneClassificationSchema,
   SceneRouteSchema,
+  UISchema,
 } from './schema';
 
 describe('CommandSliceSchema', () => {
@@ -527,3 +539,212 @@ describe('QuerySliceSchema', () => {
     }
   });
 });
+
+describe('RegionEntrySchema', () => {
+  it('should accept valid region entry with required fields', () => {
+    const result = RegionEntrySchema.safeParse({ id: 'hero-1', name: 'HeroBanner' });
+    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 reject missing name', () => {
+    const result = RegionEntrySchema.safeParse({ id: 'card-1' });
+    expect(result.success).toBe(false);
+  });
+});
+
+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);
+  });
+
+  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 missing layoutId', () => {
+    const result = UISchema.safeParse({ mode: 'as-is', regions: {} });
+    expect(result.success).toBe(false);
+  });
+
+  it('should reject missing mode', () => {
+    const result = UISchema.safeParse({ layoutId: 'l', regions: {} });
+    expect(result.success).toBe(false);
+  });
+
+  it('should reject missing regions', () => {
+    const result = UISchema.safeParse({ layoutId: 'l', mode: 'as-is' });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('ComponentDefinitionSchema', () => {
+  it('should accept valid component definition', () => {
+    const result = ComponentDefinitionSchema.safeParse({
+      id: 'comp-1',
+      name: 'PriceTag',
+      category: 'commerce',
+      description: 'Displays a price',
+      slots: { price: { type: 'number' } },
+      template: '<span>{{price}}</span>',
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual({
+        id: 'comp-1',
+        name: 'PriceTag',
+        category: 'commerce',
+        description: 'Displays a price',
+        slots: { price: { type: 'number' } },
+        template: '<span>{{price}}</span>',
+      });
+    }
+  });
+
+  it('should reject missing required fields', () => {
+    const result = ComponentDefinitionSchema.safeParse({ id: 'comp-1', name: 'PriceTag' });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('DesignSchema ui field', () => {
+  it('should accept design with optional ui', () => {
+    const result = DesignSchema.safeParse({
+      ui: {
+        layoutId: 'sidebar',
+        mode: 'as-is',
+        regions: { sidebar: [{ id: 'nav', name: 'NavMenu' }] },
+      },
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.ui?.layoutId).toBe('sidebar');
+    }
+  });
+
+  it('should accept design without ui', () => {
+    const result = DesignSchema.safeParse({});
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.ui).toBeUndefined();
+    }
+  });
+});
+
+describe('modelSchema design.components field', () => {
+  const minimalModel = {
+    variant: 'specs' as const,
+    narratives: [],
+    messages: [],
+    modules: [],
+  };
+
+  it('should accept model with design.components', () => {
+    const result = modelSchema.safeParse({
+      ...minimalModel,
+      design: {
+        components: [
+          {
+            id: 'comp-1',
+            name: 'PriceTag',
+            category: 'commerce',
+            description: 'Displays a price',
+            slots: { price: { type: 'number' } },
+            template: '<span>{{price}}</span>',
+          },
+        ],
+      },
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.design?.components).toHaveLength(1);
+      expect(result.data.design?.components?.[0].name).toBe('PriceTag');
+    }
+  });
+
+  it('should accept model design without components', () => {
+    const result = modelSchema.safeParse({
+      ...minimalModel,
+      design: {},
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.design?.components).toBeUndefined();
+    }
+  });
+});
+
+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('UI type matches UISchema inference', () => {
+    const parsed = UISchema.parse({ layoutId: 'l', mode: 'as-is', regions: {} });
+    const typed: UI = parsed;
+    expect(typed).toEqual({ layoutId: 'l', mode: 'as-is', regions: {} });
+  });
+
+  it('ComponentDefinition type matches ComponentDefinitionSchema inference', () => {
+    const parsed = ComponentDefinitionSchema.parse({
+      id: 'c-1',
+      name: 'Btn',
+      category: 'ui',
+      description: 'A button',
+      slots: {},
+      template: '<button/>',
+    });
+    const typed: ComponentDefinition = parsed;
+    expect(typed.name).toBe('Btn');
+  });
+});

package/src/schema.ts

@@ -218,10 +218,39 @@ export const ImageAssetSchema = z
   })
   .describe('Image asset with optional generation metadata');
 
+const RegionEntrySchema = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+    slots: z.record(z.unknown()).optional(),
+  })
+  .describe('Component placed in a layout region');
+
+const UISchema = z
+  .object({
+    layoutId: z.string(),
+    mode: z.enum(['as-is', 'modify', 'custom']),
+    regions: z.record(z.array(RegionEntrySchema)),
+    customizationNotes: z.string().optional(),
+  })
+  .describe('UI composition for a slice');
+
+const ComponentDefinitionSchema = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+    category: z.string(),
+    description: z.string(),
+    slots: z.record(z.unknown()),
+    template: z.string(),
+  })
+  .describe('Custom reusable component definition');
+
 export const DesignSchema = z
   .object({
     imageAsset: ImageAssetSchema.optional().describe('Primary image asset for this entity'),
     metadata: z.record(z.unknown()).optional().describe('Flexible design metadata'),
+    ui: UISchema.optional().describe('UI composition for this entity'),
   })
   .describe('Design fields for visual representation');
 
@@ -513,6 +542,10 @@ export const ClientServerNamesSchema = z
   })
   .describe('System with client/server descriptions for behavior planning');
 
+const ModelDesignSchema = DesignSchema.extend({
+  components: z.array(ComponentDefinitionSchema).optional().describe('Custom reusable component definitions'),
+}).describe('Model-level design fields with component definitions');
+
 export const modelSchema = z
   .object({
     variant: z.literal('specs').describe('Full specification with all details'),
@@ -521,7 +554,7 @@ export const modelSchema = z
     integrations: z.array(IntegrationSchema).optional(),
     modules: z.array(ModuleSchema).describe('Modules for type ownership and file grouping'),
     journeys: z.array(JourneySchema).optional(),
-    design: DesignSchema.optional().describe('Design fields for visual representation'),
+    design: ModelDesignSchema.optional().describe('Design fields for visual representation'),
   })
   .describe('Complete system specification with all implementation details');
 
@@ -551,6 +584,9 @@ export {
   StepErrorSchema,
   StepWithDocStringSchema,
   StepWithErrorSchema,
+  RegionEntrySchema,
+  UISchema,
+  ComponentDefinitionSchema,
 };
 
 export type Model = z.infer<typeof modelSchema>;
@@ -577,3 +613,6 @@ export type SceneRoute = z.infer<typeof SceneRouteSchema>;
 export type JourneyPlanning = z.infer<typeof JourneyPlanningSchema>;
 export type ImageAsset = z.infer<typeof ImageAssetSchema>;
 export type Design = z.infer<typeof DesignSchema>;
+export type RegionEntry = z.infer<typeof RegionEntrySchema>;
+export type UI = z.infer<typeof UISchema>;
+export type ComponentDefinition = z.infer<typeof ComponentDefinitionSchema>;