@vylos/core 0.1.0

package/tests/engine/schemas.test.ts

@@ -0,0 +1,250 @@
+import { describe, it, expect } from 'vitest';
+import { baseGameStateSchema, extendGameStateSchema } from '../../src/engine/schemas/baseGameState.schema';
+import { engineStateSchema, engineSettingsSchema } from '../../src/engine/schemas/engineState.schema';
+import { checkpointSchema } from '../../src/engine/schemas/checkpoint.schema';
+import { locationSchema, locationLinkSchema } from '../../src/engine/schemas/location.schema';
+import { z } from 'zod';
+
+describe('baseGameStateSchema', () => {
+  const validState = {
+    locationId: 'bedroom',
+    gameTime: 8,
+    flags: { intro_done: true },
+    counters: { coffee_count: 2 },
+    player: { name: 'Alice' },
+  };
+
+  it('validates a correct base game state', () => {
+    const result = baseGameStateSchema.safeParse(validState);
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects empty locationId', () => {
+    const result = baseGameStateSchema.safeParse({ ...validState, locationId: '' });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects negative gameTime', () => {
+    const result = baseGameStateSchema.safeParse({ ...validState, gameTime: -1 });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects empty player name', () => {
+    const result = baseGameStateSchema.safeParse({
+      ...validState,
+      player: { name: '' },
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects missing fields', () => {
+    const result = baseGameStateSchema.safeParse({ locationId: 'test' });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('extendGameStateSchema', () => {
+  it('extends base schema with custom fields', () => {
+    const extended = extendGameStateSchema({
+      reputation: z.number(),
+      inventory: z.array(z.string()),
+    });
+
+    const result = extended.safeParse({
+      locationId: 'cafe',
+      gameTime: 14,
+      flags: {},
+      counters: {},
+      player: { name: 'Bob' },
+      reputation: 50,
+      inventory: ['key', 'map'],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects extended state missing custom fields', () => {
+    const extended = extendGameStateSchema({
+      reputation: z.number(),
+    });
+
+    const result = extended.safeParse({
+      locationId: 'cafe',
+      gameTime: 14,
+      flags: {},
+      counters: {},
+      player: { name: 'Bob' },
+      // missing reputation
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('engineStateSchema', () => {
+  const validEngineState = {
+    phase: 'created',
+    background: null,
+    foreground: null,
+    dialogue: null,
+    choices: null,
+    currentLocationId: null,
+    availableActions: [],
+    availableLocations: [],
+    menuOpen: null,
+    skipMode: false,
+    autoMode: false,
+  };
+
+  it('validates initial engine state', () => {
+    const result = engineStateSchema.safeParse(validEngineState);
+    expect(result.success).toBe(true);
+  });
+
+  it('validates engine state with dialogue', () => {
+    const result = engineStateSchema.safeParse({
+      ...validEngineState,
+      phase: 'running',
+      dialogue: { text: 'Hello', speaker: 'Alice', isNarration: false },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('validates engine state with choices', () => {
+    const result = engineStateSchema.safeParse({
+      ...validEngineState,
+      phase: 'running',
+      choices: {
+        prompt: null,
+        options: [
+          { text: 'Yes', value: 'yes' },
+          { text: 'No', value: 'no' },
+        ],
+      },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects invalid phase', () => {
+    const result = engineStateSchema.safeParse({
+      ...validEngineState,
+      phase: 'invalid',
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('engineSettingsSchema', () => {
+  it('validates default settings', () => {
+    const result = engineSettingsSchema.safeParse({
+      textSpeed: 0.5,
+      autoSpeed: 0.5,
+      volume: { master: 1, music: 0.8, sfx: 0.8, voice: 1 },
+      language: 'en',
+      fullscreen: false,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects volume out of range', () => {
+    const result = engineSettingsSchema.safeParse({
+      textSpeed: 0.5,
+      autoSpeed: 0.5,
+      volume: { master: 1.5, music: 0.8, sfx: 0.8, voice: 1 },
+      language: 'en',
+      fullscreen: false,
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('checkpointSchema', () => {
+  it('validates a say checkpoint', () => {
+    const result = checkpointSchema.safeParse({
+      step: 0,
+      gameState: {
+        locationId: 'cafe',
+        gameTime: 14,
+        flags: {},
+        counters: {},
+        player: { name: 'Alice' },
+      },
+      type: 'say',
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('validates a choice checkpoint with result', () => {
+    const result = checkpointSchema.safeParse({
+      step: 1,
+      gameState: {
+        locationId: 'cafe',
+        gameTime: 14,
+        flags: {},
+        counters: {},
+        player: { name: 'Alice' },
+      },
+      type: 'choice',
+      choiceResult: 'coffee',
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects negative step number', () => {
+    const result = checkpointSchema.safeParse({
+      step: -1,
+      gameState: {
+        locationId: 'cafe',
+        gameTime: 14,
+        flags: {},
+        counters: {},
+        player: { name: 'Alice' },
+      },
+      type: 'say',
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('locationSchema', () => {
+  it('validates a location with backgrounds', () => {
+    const result = locationSchema.safeParse({
+      id: 'cafe',
+      name: 'The Cafe',
+      backgrounds: [
+        { path: '/assets/cafe_day.jpg', timeRange: [6, 18] },
+        { path: '/assets/cafe_night.jpg', timeRange: [18, 6] },
+        { path: '/assets/cafe_default.jpg' },
+      ],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('validates a location with i18n name', () => {
+    const result = locationSchema.safeParse({
+      id: 'cafe',
+      name: { en: 'The Cafe', fr: 'Le Café' },
+      backgrounds: [{ path: '/assets/cafe.jpg' }],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects empty location id', () => {
+    const result = locationSchema.safeParse({
+      id: '',
+      name: 'Test',
+      backgrounds: [],
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('locationLinkSchema', () => {
+  it('validates a link', () => {
+    const result = locationLinkSchema.safeParse({ from: 'bedroom', to: 'hallway' });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects empty from', () => {
+    const result = locationLinkSchema.safeParse({ from: '', to: 'hallway' });
+    expect(result.success).toBe(false);
+  });
+});

package/tests/engine/utils.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest';
+import { resolveBackground, formatGameTime, interpolate } from '../../src/engine/utils/TimeHelper';
+
+describe('resolveBackground', () => {
+  const backgrounds = [
+    { path: '/day.jpg', timeRange: [6, 18] as [number, number] },
+    { path: '/night.jpg', timeRange: [18, 6] as [number, number] },
+    { path: '/default.jpg' },
+  ];
+
+  it('returns daytime background during day', () => {
+    expect(resolveBackground(backgrounds, 12)).toBe('/day.jpg');
+  });
+
+  it('returns night background at night', () => {
+    expect(resolveBackground(backgrounds, 22)).toBe('/night.jpg');
+  });
+
+  it('returns night background at midnight', () => {
+    expect(resolveBackground(backgrounds, 0)).toBe('/night.jpg');
+  });
+
+  it('returns default when no time match', () => {
+    const bgs = [{ path: '/default.jpg' }];
+    expect(resolveBackground(bgs, 12)).toBe('/default.jpg');
+  });
+
+  it('returns null for empty array', () => {
+    expect(resolveBackground([], 12)).toBeNull();
+  });
+
+  it('wraps time past 24 hours', () => {
+    expect(resolveBackground(backgrounds, 36)).toBe('/day.jpg');  // 36 % 24 = 12
+  });
+});
+
+describe('formatGameTime', () => {
+  it('formats morning time', () => {
+    expect(formatGameTime(8)).toBe('08:00');
+  });
+
+  it('formats afternoon time with minutes', () => {
+    expect(formatGameTime(14.5)).toBe('14:30');
+  });
+
+  it('formats midnight', () => {
+    expect(formatGameTime(0)).toBe('00:00');
+  });
+
+  it('wraps past 24', () => {
+    expect(formatGameTime(25.5)).toBe('01:30');
+  });
+});
+
+describe('interpolate', () => {
+  it('replaces single variable', () => {
+    expect(interpolate('Hello {name}!', { name: 'Alice' })).toBe('Hello Alice!');
+  });
+
+  it('replaces multiple variables', () => {
+    expect(interpolate('{a} and {b}', { a: 'X', b: 'Y' })).toBe('X and Y');
+  });
+
+  it('leaves unknown variables untouched', () => {
+    expect(interpolate('Hello {name}!', {})).toBe('Hello {name}!');
+  });
+
+  it('handles numeric values', () => {
+    expect(interpolate('Count: {n}', { n: 42 })).toBe('Count: 42');
+  });
+
+  it('handles text without variables', () => {
+    expect(interpolate('No vars here', { name: 'Alice' })).toBe('No vars here');
+  });
+});

package/tests/integration/game-loop.test.ts

@@ -0,0 +1,201 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { EventRunner, type EventRunnerCallbacks } from '../../src/engine/core/EventRunner';
+import { EventManager } from '../../src/engine/managers/EventManager';
+import { HistoryManager } from '../../src/engine/managers/HistoryManager';
+import { NavigationManager } from '../../src/engine/managers/NavigationManager';
+import { SaveManager } from '../../src/engine/managers/SaveManager';
+import { SettingsManager } from '../../src/engine/managers/SettingsManager';
+import { VylosStorage } from '../../src/engine/storage/VylosStorage';
+import { Engine } from '../../src/engine/core/Engine';
+import type { VylosAPI, VylosEvent, BaseGameState } from '../../src/engine/types';
+import { createEngine, clearComponentOverrides, getComponentOverride } from '../../src/engine/core/EngineFactory';
+import type { VylosPlugin } from '../../src/engine/types';
+import { defineComponent } from 'vue';
+
+function makeState(overrides: Partial<BaseGameState> = {}): BaseGameState {
+  return {
+    locationId: 'cafe',
+    gameTime: 8,
+    flags: {},
+    counters: {},
+    player: { name: 'Alice' },
+    ...overrides,
+  };
+}
+
+function makeCallbacks(state?: BaseGameState): EventRunnerCallbacks & { state: BaseGameState } {
+  const s = state ?? makeState();
+  return {
+    state: s,
+    onSay: vi.fn(),
+    onChoice: vi.fn(),
+    onSetBackground: vi.fn(),
+    onSetForeground: vi.fn(),
+    onShowOverlay: vi.fn(),
+    onHideOverlay: vi.fn(),
+    onSetLocation: vi.fn(),
+    onClear: vi.fn(),
+    resolveText: vi.fn((text: unknown) => typeof text === 'string' ? text : 'resolved'),
+    getState: vi.fn(() => s),
+    setState: vi.fn((newState: BaseGameState) => { Object.assign(s, newState); }),
+  };
+}
+
+describe('Game loop integration', () => {
+  it('executes an event, locks it, and records history', async () => {
+    const callbacks = makeCallbacks();
+    const eventRunner = new EventRunner(callbacks);
+    const eventManager = new EventManager();
+    const historyManager = new HistoryManager();
+    const navigationManager = new NavigationManager();
+    const storage = new VylosStorage('test-loop-1');
+    await storage.open();
+    const saveManager = new SaveManager(storage);
+    const settingsManager = new SettingsManager(storage);
+
+    const engine = new Engine({
+      eventManager,
+      historyManager,
+      navigationManager,
+      eventRunner,
+      saveManager,
+      settingsManager,
+    });
+
+    const event: VylosEvent = {
+      id: 'intro',
+      async execute(api: VylosAPI) {
+        await api.say('Hello');
+        await api.say('World');
+      },
+    };
+
+    // Start engine in background
+    const runPromise = engine.run([event], callbacks.getState);
+
+    // Wait for first say
+    await vi.waitFor(() => expect(callbacks.onSay).toHaveBeenCalledWith('Hello', null));
+    eventRunner.resolveWait();
+
+    // Wait for second say
+    await vi.waitFor(() => expect(callbacks.onSay).toHaveBeenCalledWith('World', null));
+    eventRunner.resolveWait();
+
+    // Event complete — now we need to handle navigation wait
+    // Give engine a tick to process completion
+    await new Promise(r => setTimeout(r, 50));
+
+    // Stop engine
+    engine.stop();
+    await runPromise;
+
+    // Verify event was locked
+    expect(eventManager.getStatus('intro')).toBe('locked');
+    // Verify history recorded
+    expect(historyManager.count).toBe(1);
+    expect(historyManager.current?.eventId).toBe('intro');
+  });
+
+  it('handles jump between events', async () => {
+    const callbacks = makeCallbacks();
+    const eventRunner = new EventRunner(callbacks);
+    const eventManager = new EventManager();
+    const historyManager = new HistoryManager();
+    const navigationManager = new NavigationManager();
+    const storage = new VylosStorage('test-loop-2');
+    await storage.open();
+    const saveManager = new SaveManager(storage);
+    const settingsManager = new SettingsManager(storage);
+
+    const engine = new Engine({
+      eventManager,
+      historyManager,
+      navigationManager,
+      eventRunner,
+      saveManager,
+      settingsManager,
+    });
+
+    const spoken: string[] = [];
+    callbacks.onSay = vi.fn((text: string) => spoken.push(text));
+
+    const events: VylosEvent[] = [
+      {
+        id: 'first',
+        async execute(api: VylosAPI) {
+          await api.say('In first event');
+          api.jump('second');
+        },
+      },
+      {
+        id: 'second',
+        async execute(api: VylosAPI) {
+          await api.say('In second event');
+        },
+      },
+    ];
+
+    const runPromise = engine.run(events, callbacks.getState);
+
+    // First event: "In first event"
+    await vi.waitFor(() => expect(spoken).toContain('In first event'));
+    eventRunner.resolveWait();
+
+    // After jump, second event: "In second event"
+    await vi.waitFor(() => expect(spoken).toContain('In second event'));
+    eventRunner.resolveWait();
+
+    await new Promise(r => setTimeout(r, 50));
+    engine.stop();
+    await runPromise;
+
+    expect(spoken).toEqual(['In first event', 'In second event']);
+    expect(historyManager.count).toBe(2);
+  });
+});
+
+describe('DI / Plugin system', () => {
+  beforeEach(() => {
+    clearComponentOverrides();
+  });
+
+  it('createEngine produces a working engine', () => {
+    const callbacks = makeCallbacks();
+    const engine = createEngine({ callbacks });
+    expect(engine).toBeDefined();
+    expect(engine.eventManager).toBeInstanceOf(EventManager);
+    expect(engine.historyManager).toBeInstanceOf(HistoryManager);
+    expect(engine.navigationManager).toBeInstanceOf(NavigationManager);
+  });
+
+  it('plugin can override a manager', () => {
+    class CustomEventManager extends EventManager {
+      readonly isCustom = true;
+    }
+
+    const plugin: VylosPlugin = {
+      setup(container) {
+        container.register('EventManager', { useClass: CustomEventManager });
+      },
+    };
+
+    const callbacks = makeCallbacks();
+    const engine = createEngine({ callbacks, plugin });
+    expect((engine.eventManager as CustomEventManager).isCustom).toBe(true);
+  });
+
+  it('plugin can register component overrides', () => {
+    const CustomTopBar = defineComponent({ template: '<div>Custom</div>' });
+
+    const plugin: VylosPlugin = {
+      components: {
+        TopBar: CustomTopBar,
+      },
+    };
+
+    const callbacks = makeCallbacks();
+    createEngine({ callbacks, plugin });
+    expect(getComponentOverride('TopBar')).toBe(CustomTopBar);
+    expect(getComponentOverride('NonExistent')).toBeUndefined();
+  });
+});

package/tests/safety/event-validation.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'vitest';
+import { baseGameStateSchema, extendGameStateSchema } from '../../src/engine/schemas/baseGameState.schema';
+import { StateValidationError } from '../../src/engine/errors/StateValidationError';
+import { z } from 'zod';
+
+/**
+ * Tests for the Zod validation gate that runs after event execution.
+ * The engine validates state after each event to prevent corruption.
+ */
+describe('Event validation gate', () => {
+  function validateState(schema: z.ZodSchema, state: unknown): { valid: boolean; error?: StateValidationError } {
+    const result = schema.safeParse(state);
+    if (result.success) return { valid: true };
+    return { valid: false, error: new StateValidationError(result.error) };
+  }
+
+  it('accepts valid state after event execution', () => {
+    const state = {
+      locationId: 'cafe',
+      gameTime: 14,
+      flags: { intro_done: true },
+      counters: { coffee: 1 },
+      player: { name: 'Alice' },
+    };
+
+    const { valid } = validateState(baseGameStateSchema, state);
+    expect(valid).toBe(true);
+  });
+
+  it('rejects state with corrupted locationId', () => {
+    const state = {
+      locationId: '',
+      gameTime: 14,
+      flags: {},
+      counters: {},
+      player: { name: 'Alice' },
+    };
+
+    const { valid, error } = validateState(baseGameStateSchema, state);
+    expect(valid).toBe(false);
+    expect(error?.message).toContain('locationId');
+  });
+
+  it('rejects state with wrong type for flags', () => {
+    const state = {
+      locationId: 'cafe',
+      gameTime: 14,
+      flags: 'not-an-object',
+      counters: {},
+      player: { name: 'Alice' },
+    };
+
+    const { valid } = validateState(baseGameStateSchema, state);
+    expect(valid).toBe(false);
+  });
+
+  it('validates extended project schema', () => {
+    const projectSchema = extendGameStateSchema({
+      reputation: z.number().min(0).max(100),
+      inventory: z.array(z.string()),
+      npcRelations: z.record(z.string(), z.number().min(-100).max(100)),
+    });
+
+    // Simulates an event that correctly modified state
+    const goodState = {
+      locationId: 'cafe',
+      gameTime: 14,
+      flags: { intro_done: true },
+      counters: {},
+      player: { name: 'Alice' },
+      reputation: 50,
+      inventory: ['map', 'key'],
+      npcRelations: { barista: 10, landlord: -5 },
+    };
+    expect(validateState(projectSchema, goodState).valid).toBe(true);
+
+    // Simulates a buggy event that set reputation to 150
+    const badState = { ...goodState, reputation: 150 };
+    const result = validateState(projectSchema, badState);
+    expect(result.valid).toBe(false);
+    expect(result.error?.message).toContain('reputation');
+  });
+
+  it('rejects prototype pollution attempts', () => {
+    const state = {
+      locationId: 'cafe',
+      gameTime: 14,
+      flags: {},
+      counters: {},
+      player: { name: 'Alice' },
+      __proto__: { isAdmin: true },
+    };
+
+    // Zod parses with structuredClone behavior, __proto__ not a valid field
+    const result = baseGameStateSchema.safeParse(state);
+    // Should either succeed (ignoring __proto__) or fail — both are safe
+    // The important thing is that isAdmin is NOT in the result
+    if (result.success) {
+      expect((result.data as Record<string, unknown>)['isAdmin']).toBeUndefined();
+    }
+  });
+});