@holoscript/framework 6.0.3

package/src/ai/__tests__/PromptTemplates.prod.test.ts

@@ -0,0 +1,313 @@
+/**
+ * PromptTemplates — Production Tests
+ *
+ * Tests: PromptTemplateSystem (getAvailableTemplates, getTemplatesByCategory, getTemplate,
+ * createPrompt, validateContext, registerTemplate, suggestTemplates, getCategories, createBatch)
+ * and QuickPrompts (object, interactive, physics, player, networked).
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PromptTemplateSystem, QuickPrompts } from '../PromptTemplates';
+import type { PromptTemplate, TemplateContext } from '../PromptTemplates';
+
+function makeCustomTemplate(overrides: Partial<PromptTemplate> = {}): PromptTemplate {
+  return {
+    id: 'custom-001',
+    name: 'Custom Template',
+    description: 'A custom test template',
+    category: 'custom',
+    template: 'Create a {{shape}} with {{color}}',
+    variables: ['shape', 'color'],
+    examples: ['Create a box with red'],
+    bestFor: 'testing',
+    ...overrides,
+  };
+}
+
+describe('PromptTemplateSystem — getAvailableTemplates', () => {
+  let pts: PromptTemplateSystem;
+  beforeEach(() => {
+    pts = new PromptTemplateSystem();
+  });
+
+  it('returns a non-empty array of built-in templates', () => {
+    const templates = pts.getAvailableTemplates();
+    expect(templates.length).toBeGreaterThan(0);
+  });
+
+  it('each template has required fields', () => {
+    for (const t of pts.getAvailableTemplates()) {
+      expect(typeof t.id).toBe('string');
+      expect(typeof t.name).toBe('string');
+      expect(typeof t.category).toBe('string');
+      expect(Array.isArray(t.variables)).toBe(true);
+      expect(Array.isArray(t.examples)).toBe(true);
+    }
+  });
+
+  it('includes built-in basic-object template', () => {
+    const ids = pts.getAvailableTemplates().map((t) => t.id);
+    expect(ids).toContain('basic-object');
+  });
+
+  it('custom templates are included after registration', () => {
+    pts.registerTemplate(makeCustomTemplate());
+    const ids = pts.getAvailableTemplates().map((t) => t.id);
+    expect(ids).toContain('custom-001');
+  });
+});
+
+describe('PromptTemplateSystem — getTemplatesByCategory', () => {
+  let pts: PromptTemplateSystem;
+  beforeEach(() => {
+    pts = new PromptTemplateSystem();
+  });
+
+  it('returns templates for "basic" category', () => {
+    const results = pts.getTemplatesByCategory('basic');
+    expect(results.length).toBeGreaterThan(0);
+    expect(results.every((t) => t.category === 'basic')).toBe(true);
+  });
+
+  it('returns empty array for unknown category', () => {
+    expect(pts.getTemplatesByCategory('nonexistent')).toHaveLength(0);
+  });
+
+  it('returns ui category templates only', () => {
+    const results = pts.getTemplatesByCategory('ui');
+    expect(results.every((t) => t.category === 'ui')).toBe(true);
+    expect(results.length).toBeGreaterThan(0);
+  });
+});
+
+describe('PromptTemplateSystem — getTemplate', () => {
+  let pts: PromptTemplateSystem;
+  beforeEach(() => {
+    pts = new PromptTemplateSystem();
+  });
+
+  it('returns a built-in template by id', () => {
+    const t = pts.getTemplate('basic-object');
+    expect(t).not.toBeNull();
+    expect(t!.id).toBe('basic-object');
+  });
+
+  it('returns null for unknown id', () => {
+    expect(pts.getTemplate('does-not-exist')).toBeNull();
+  });
+
+  it('returns registered custom template', () => {
+    pts.registerTemplate(makeCustomTemplate({ id: 'my-custom' }));
+    expect(pts.getTemplate('my-custom')).not.toBeNull();
+  });
+
+  it('custom template takes precedence (same id would override)', () => {
+    pts.registerTemplate(makeCustomTemplate({ id: 'physics-object', name: 'Override' }));
+    const t = pts.getTemplate('physics-object');
+    // custom map is checked after built-in; built-in wins due to || chain
+    expect(t).not.toBeNull();
+  });
+});
+
+describe('PromptTemplateSystem — createPrompt', () => {
+  let pts: PromptTemplateSystem;
+  beforeEach(() => {
+    pts = new PromptTemplateSystem();
+  });
+
+  it('replaces all variables in template', () => {
+    const result = pts.createPrompt('basic-object', {
+      geometry: 'sphere',
+      color: 'red',
+      position: '[0,1,0]',
+    });
+    expect(result).toContain('sphere');
+    expect(result).toContain('red');
+    expect(result).toContain('[0,1,0]');
+    expect(result).not.toContain('{{');
+  });
+
+  it('throws for unknown template id', () => {
+    expect(() => pts.createPrompt('no-such-template', {})).toThrow();
+  });
+
+  it('leaves un-provided variables as placeholders', () => {
+    const result = pts.createPrompt('basic-object', { geometry: 'cube' });
+    expect(result).toContain('{{color}}');
+  });
+
+  it('handles number values in context', () => {
+    const result = pts.createPrompt('physics-object', {
+      geometry: 'sphere',
+      physics_type: 'dynamic',
+      mass: 2.5,
+      restitution: 0.7,
+    });
+    expect(result).toContain('2.5');
+    expect(result).toContain('0.7');
+  });
+
+  it('handles boolean values in context', () => {
+    pts.registerTemplate(makeCustomTemplate({ template: 'Flag: {{flag}}', variables: ['flag'] }));
+    const result = pts.createPrompt('custom-001', { flag: true });
+    expect(result).toContain('true');
+  });
+
+  it('replaces multiple occurrences of same variable', () => {
+    pts.registerTemplate(makeCustomTemplate({ template: '{{x}} and {{x}}', variables: ['x'] }));
+    const result = pts.createPrompt('custom-001', { x: 'HELLO' });
+    expect(result).toBe('HELLO and HELLO');
+  });
+});
+
+describe('PromptTemplateSystem — validateContext', () => {
+  let pts: PromptTemplateSystem;
+  beforeEach(() => {
+    pts = new PromptTemplateSystem();
+  });
+
+  it('valid=true when all variables provided', () => {
+    const { valid, missing } = pts.validateContext('basic-object', {
+      geometry: 'cube',
+      color: 'red',
+      position: '[0,0,0]',
+    });
+    expect(valid).toBe(true);
+    expect(missing).toHaveLength(0);
+  });
+
+  it('valid=false when variables are missing', () => {
+    const { valid, missing } = pts.validateContext('basic-object', { geometry: 'cube' });
+    expect(valid).toBe(false);
+    expect(missing).toContain('color');
+    expect(missing).toContain('position');
+  });
+
+  it('returns valid=false for unknown template', () => {
+    const { valid, missing } = pts.validateContext('bogus', {});
+    expect(valid).toBe(false);
+    expect(missing.length).toBeGreaterThan(0);
+  });
+
+  it('extra context keys do not cause false positive', () => {
+    const { valid } = pts.validateContext('basic-object', {
+      geometry: 'cube',
+      color: 'blue',
+      position: '[0,0,0]',
+      extra: 'ignored',
+    });
+    expect(valid).toBe(true);
+  });
+});
+
+describe('PromptTemplateSystem — registerTemplate / getCategories / suggestTemplates', () => {
+  let pts: PromptTemplateSystem;
+  beforeEach(() => {
+    pts = new PromptTemplateSystem();
+  });
+
+  it('getCategories returns sorted unique category names', () => {
+    const cats = pts.getCategories();
+    expect(cats.length).toBeGreaterThan(0);
+    const sorted = [...cats].sort();
+    expect(cats).toEqual(sorted);
+    expect(new Set(cats).size).toBe(cats.length);
+  });
+
+  it('custom category appears in getCategories after registration', () => {
+    pts.registerTemplate(makeCustomTemplate({ category: 'unicorn' }));
+    expect(pts.getCategories()).toContain('unicorn');
+  });
+
+  it('suggestTemplates returns subset matching query', () => {
+    const results = pts.suggestTemplates('basic', 'object');
+    expect(results.length).toBeLessThanOrEqual(5);
+    expect(results.every((t) => t.category === 'basic')).toBe(true);
+  });
+
+  it('suggestTemplates returns all in category when no query', () => {
+    const results = pts.suggestTemplates('basic');
+    expect(results.length).toBeGreaterThan(0);
+  });
+
+  it('suggestTemplates returns empty for unknown category', () => {
+    expect(pts.suggestTemplates('noop')).toHaveLength(0);
+  });
+});
+
+describe('PromptTemplateSystem — createBatch', () => {
+  let pts: PromptTemplateSystem;
+  beforeEach(() => {
+    pts = new PromptTemplateSystem();
+  });
+
+  it('returns array of same length as input', () => {
+    const batch = pts.createBatch([
+      {
+        templateId: 'basic-object',
+        context: { geometry: 'box', color: 'blue', position: '[0,0,0]' },
+      },
+      {
+        templateId: 'basic-object',
+        context: { geometry: 'sphere', color: 'red', position: '[1,0,0]' },
+      },
+    ]);
+    expect(batch).toHaveLength(2);
+  });
+
+  it('each result is a string with variables substituted', () => {
+    const batch = pts.createBatch([
+      {
+        templateId: 'basic-object',
+        context: { geometry: 'cube', color: 'green', position: '[0,0,0]' },
+      },
+    ]);
+    expect(batch[0]).toContain('cube');
+    expect(batch[0]).toContain('green');
+  });
+
+  it('returns empty array for empty input', () => {
+    expect(pts.createBatch([])).toHaveLength(0);
+  });
+});
+
+describe('QuickPrompts', () => {
+  it('object() returns string containing geometry and color', () => {
+    const p = QuickPrompts.object('sphere', 'blue', [0, 1, 0]);
+    expect(typeof p).toBe('string');
+    expect(p).toContain('sphere');
+    expect(p).toContain('blue');
+  });
+
+  it('object() encodes position as JSON', () => {
+    const p = QuickPrompts.object('cube', 'red', [1, 2, 3]);
+    expect(p).toContain('[1,2,3]');
+  });
+
+  it('interactive() returns string with all provided params', () => {
+    const p = QuickPrompts.interactive('green', 'cube', 'responds to touch', 'feedback');
+    expect(p).toContain('green');
+    expect(p).toContain('cube');
+    expect(p).toContain('responds to touch');
+    expect(p).toContain('feedback');
+  });
+
+  it('physics() returns string with mass and restitution', () => {
+    const p = QuickPrompts.physics('sphere', 'dynamic', 2.5, 0.8);
+    expect(p).toContain('2.5');
+    expect(p).toContain('0.8');
+  });
+
+  it('player() returns string with movement type and health', () => {
+    const p = QuickPrompts.player('humanoid', 'WASD', 100, 'jump,dash');
+    expect(p).toContain('WASD');
+    expect(p).toContain('100');
+    expect(p).toContain('jump,dash');
+  });
+
+  it('networked() includes owner_type default first-grabber', () => {
+    const p = QuickPrompts.networked('ball', 'position,rotation', 20);
+    expect(p).toContain('first-grabber');
+    expect(p).toContain('20');
+  });
+});

package/src/ai/__tests__/PromptTemplates.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PromptTemplateSystem, QuickPrompts } from '../PromptTemplates';
+
+describe('PromptTemplateSystem', () => {
+  let sys: PromptTemplateSystem;
+
+  beforeEach(() => {
+    sys = new PromptTemplateSystem();
+  });
+
+  // Built-in templates
+  it('getAvailableTemplates returns built-ins', () => {
+    const templates = sys.getAvailableTemplates();
+    expect(templates.length).toBeGreaterThan(0);
+    expect(templates.some((t) => t.id === 'basic-object')).toBe(true);
+  });
+
+  it('getTemplate returns specific template', () => {
+    const t = sys.getTemplate('basic-object');
+    expect(t).not.toBeNull();
+    expect(t!.category).toBe('basic');
+  });
+
+  it('getTemplate returns null for unknown', () => {
+    expect(sys.getTemplate('nonexistent')).toBeNull();
+  });
+
+  // Category
+  it('getTemplatesByCategory filters', () => {
+    const basic = sys.getTemplatesByCategory('basic');
+    expect(basic.length).toBeGreaterThan(0);
+    expect(basic.every((t) => t.category === 'basic')).toBe(true);
+  });
+
+  it('getCategories returns unique categories', () => {
+    const cats = sys.getCategories();
+    expect(cats.length).toBeGreaterThan(0);
+    expect(new Set(cats).size).toBe(cats.length);
+  });
+
+  // Prompt creation
+  it('createPrompt interpolates variables', () => {
+    const prompt = sys.createPrompt('basic-object', {
+      color: 'blue',
+      geometry: 'sphere',
+      position: '[0,1,0]',
+    });
+    expect(prompt).toContain('blue');
+    expect(prompt).toContain('sphere');
+  });
+
+  it('createPrompt leaves unmatched variables as placeholders', () => {
+    const prompt = sys.createPrompt('basic-object', { color: 'red' });
+    // Missing variables remain as {{var}}
+    expect(prompt).toContain('red');
+  });
+
+  // Validation
+  it('validateContext reports missing variables', () => {
+    const result = sys.validateContext('basic-object', {});
+    expect(result.valid).toBe(false);
+    expect(result.missing.length).toBeGreaterThan(0);
+  });
+
+  it('validateContext passes with all variables', () => {
+    const t = sys.getTemplate('basic-object')!;
+    const context: Record<string, string> = {};
+    for (const v of t.variables) context[v] = 'test';
+    const result = sys.validateContext('basic-object', context);
+    expect(result.valid).toBe(true);
+    expect(result.missing.length).toBe(0);
+  });
+
+  // Custom templates
+  it('registerTemplate adds custom template', () => {
+    sys.registerTemplate({
+      id: 'custom',
+      name: 'Custom',
+      description: 'Test',
+      category: 'custom',
+      template: 'Hello {{name}}',
+      variables: ['name'],
+      examples: [],
+      bestFor: 'test',
+    });
+    expect(sys.getTemplate('custom')).not.toBeNull();
+  });
+
+  // Suggest
+  it('suggestTemplates by category', () => {
+    const suggestions = sys.suggestTemplates('physics');
+    expect(suggestions.length).toBeGreaterThan(0);
+  });
+
+  it('suggestTemplates with query filters by name/description', () => {
+    const suggestions = sys.suggestTemplates('character', 'enemy');
+    expect(suggestions.some((t) => t.name.toLowerCase().includes('enemy'))).toBe(true);
+  });
+
+  // Batch
+  it('createBatch creates multiple prompts', () => {
+    const prompts = sys.createBatch([
+      {
+        templateId: 'basic-object',
+        context: { color: 'red', geometry: 'cube', interaction: 'grab', purpose: 'demo' },
+      },
+      {
+        templateId: 'basic-object',
+        context: { color: 'blue', geometry: 'sphere', interaction: 'touch', purpose: 'ui' },
+      },
+    ]);
+    expect(prompts.length).toBe(2);
+    expect(prompts[0]).toContain('red');
+    expect(prompts[1]).toContain('blue');
+  });
+});
+
+describe('QuickPrompts', () => {
+  it('object creates interpolated prompt', () => {
+    const p = QuickPrompts.object('sphere', 'blue', [0, 1, 0]);
+    expect(p).toContain('sphere');
+    expect(p).toContain('blue');
+  });
+
+  it('interactive creates prompt', () => {
+    const p = QuickPrompts.interactive('red', 'cube', 'hover', 'feedback');
+    expect(p).toContain('red');
+    expect(p).toContain('hover');
+  });
+
+  it('physics creates prompt', () => {
+    const p = QuickPrompts.physics('box', 'dynamic', 5, 0.5);
+    expect(p).toContain('box');
+    expect(p).toContain('dynamic');
+  });
+
+  it('player creates prompt', () => {
+    const p = QuickPrompts.player('capsule', 'fps', 100, 'jump');
+    expect(p).toContain('capsule');
+  });
+
+  it('networked creates prompt', () => {
+    const p = QuickPrompts.networked('ball', 'position,rotation', 30);
+    expect(p).toContain('ball');
+  });
+});

package/src/ai/__tests__/SemanticSearch.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest';
+import { SemanticSearchService } from '../SemanticSearchService';
+import type { AIAdapter } from '../AIAdapter';
+
+describe('SemanticSearchService', () => {
+  const mockTraits = [
+    { name: 'grabbable', description: 'Makes object grabbable by VR controllers.' },
+    { name: 'physics', description: 'Full physics simulation with gravity.' },
+    { name: 'glowing', description: 'Object emits a glow effect.' },
+  ];
+
+  it('should rank traits by similarity', async () => {
+    const mockAdapter: AIAdapter = {
+      id: 'mock',
+      name: 'Mock Adapter',
+      isReady: () => true,
+      getEmbeddings: async (text: string | string[]) => {
+        const texts = Array.isArray(text) ? text : [text];
+        return texts.map((t) => {
+          if (t.includes('grab')) return [1, 0, 0];
+          if (t.includes('physics')) return [0, 1, 0];
+          if (t.includes('glow')) return [0, 0, 1];
+          if (t.includes('hand')) return [0.9, 0, 0]; // Close to grab
+          return [0, 0, 0];
+        });
+      },
+    };
+
+    const searchService = new SemanticSearchService(mockAdapter, mockTraits);
+    await searchService.initialize();
+
+    const results = await searchService.search('something to pick up with my hand');
+
+    expect(results[0].item.name).toBe('grabbable');
+    expect(results[0].score).toBeGreaterThan(0.8);
+  });
+});

package/src/ai/__tests__/StateMachine.prod.test.ts

@@ -0,0 +1,162 @@
+/**
+ * StateMachine — Production Test Suite
+ *
+ * Covers: state management, transitions, guards, enter/exit hooks,
+ * update cycle, context, history, hierarchy (child states).
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { StateMachine } from '../StateMachine';
+
+describe('StateMachine — Production', () => {
+  // ─── State Management ─────────────────────────────────────────────
+  it('addState + getCurrentState', () => {
+    const sm = new StateMachine();
+    sm.addState({ id: 'idle' });
+    sm.setInitialState('idle');
+    expect(sm.getCurrentState()).toBe('idle');
+  });
+
+  it('no initial state → null', () => {
+    const sm = new StateMachine();
+    expect(sm.getCurrentState()).toBeNull();
+  });
+
+  it('getStateCount tracks states', () => {
+    const sm = new StateMachine();
+    sm.addState({ id: 'a' });
+    sm.addState({ id: 'b' });
+    expect(sm.getStateCount()).toBe(2);
+  });
+
+  it('removeState removes state', () => {
+    const sm = new StateMachine();
+    sm.addState({ id: 'temp' });
+    sm.removeState('temp');
+    expect(sm.getStateCount()).toBe(0);
+  });
+
+  // ─── Transitions ──────────────────────────────────────────────────
+  it('send transitions between states', () => {
+    const sm = new StateMachine();
+    sm.addState({ id: 'idle' });
+    sm.addState({ id: 'walking' });
+    sm.addTransition({ from: 'idle', to: 'walking', event: 'MOVE' });
+    sm.setInitialState('idle');
+    const result = sm.send('MOVE');
+    expect(result).toBe(true);
+    expect(sm.getCurrentState()).toBe('walking');
+  });
+
+  it('send returns false for invalid event', () => {
+    const sm = new StateMachine();
+    sm.addState({ id: 'idle' });
+    sm.setInitialState('idle');
+    expect(sm.send('NONEXISTENT')).toBe(false);
+  });
+
+  it('send returns false when no current state', () => {
+    const sm = new StateMachine();
+    expect(sm.send('X')).toBe(false);
+  });
+
+  // ─── Guards ───────────────────────────────────────────────────────
+  it('guard blocks transition when false', () => {
+    const sm = new StateMachine();
+    sm.addState({ id: 'idle' });
+    sm.addState({ id: 'attack' });
+    sm.addTransition({ from: 'idle', to: 'attack', event: 'FIGHT', guard: () => false });
+    sm.setInitialState('idle');
+    expect(sm.send('FIGHT')).toBe(false);
+    expect(sm.getCurrentState()).toBe('idle');
+  });
+
+  it('guard allows transition when true', () => {
+    const sm = new StateMachine();
+    sm.addState({ id: 'idle' });
+    sm.addState({ id: 'attack' });
+    sm.addTransition({ from: 'idle', to: 'attack', event: 'FIGHT', guard: () => true });
+    sm.setInitialState('idle');
+    expect(sm.send('FIGHT')).toBe(true);
+    expect(sm.getCurrentState()).toBe('attack');
+  });
+
+  // ─── Enter / Exit Hooks ───────────────────────────────────────────
+  it('onEnter fires when entering state', () => {
+    const spy = vi.fn();
+    const sm = new StateMachine();
+    sm.addState({ id: 'idle' });
+    sm.addState({ id: 'active', onEnter: spy });
+    sm.addTransition({ from: 'idle', to: 'active', event: 'GO' });
+    sm.setInitialState('idle');
+    sm.send('GO');
+    expect(spy).toHaveBeenCalled();
+  });
+
+  it('onExit fires when leaving state', () => {
+    const spy = vi.fn();
+    const sm = new StateMachine();
+    sm.addState({ id: 'idle', onExit: spy });
+    sm.addState({ id: 'active' });
+    sm.addTransition({ from: 'idle', to: 'active', event: 'GO' });
+    sm.setInitialState('idle');
+    sm.send('GO');
+    expect(spy).toHaveBeenCalled();
+  });
+
+  it('setInitialState fires onEnter', () => {
+    const spy = vi.fn();
+    const sm = new StateMachine();
+    sm.addState({ id: 'boot', onEnter: spy });
+    sm.setInitialState('boot');
+    expect(spy).toHaveBeenCalled();
+  });
+
+  // ─── Update ───────────────────────────────────────────────────────
+  it('update calls onUpdate for current state', () => {
+    const spy = vi.fn();
+    const sm = new StateMachine();
+    sm.addState({ id: 'idle', onUpdate: spy });
+    sm.setInitialState('idle');
+    sm.update();
+    expect(spy).toHaveBeenCalled();
+  });
+
+  // ─── Context ──────────────────────────────────────────────────────
+  it('setContext + getContext', () => {
+    const sm = new StateMachine();
+    sm.setContext('speed', 5);
+    expect(sm.getContext('speed')).toBe(5);
+  });
+
+  // ─── History ──────────────────────────────────────────────────────
+  it('getHistory tracks state transitions', () => {
+    const sm = new StateMachine();
+    sm.addState({ id: 'a' });
+    sm.addState({ id: 'b' });
+    sm.addTransition({ from: 'a', to: 'b', event: 'GO' });
+    sm.setInitialState('a');
+    sm.send('GO');
+    const history = sm.getHistory();
+    expect(history).toEqual(['a', 'b']);
+  });
+
+  // ─── isInState ────────────────────────────────────────────────────
+  it('isInState returns correct boolean', () => {
+    const sm = new StateMachine();
+    sm.addState({ id: 'idle' });
+    sm.setInitialState('idle');
+    expect(sm.isInState('idle')).toBe(true);
+    expect(sm.isInState('other')).toBe(false);
+  });
+
+  // ─── Hierarchy (Child States) ─────────────────────────────────────
+  it('getChildStates returns children', () => {
+    const sm = new StateMachine();
+    sm.addState({ id: 'combat' });
+    sm.addState({ id: 'melee', parent: 'combat' });
+    sm.addState({ id: 'ranged', parent: 'combat' });
+    sm.addState({ id: 'idle' });
+    const children = sm.getChildStates('combat');
+    expect(children.sort()).toEqual(['melee', 'ranged']);
+  });
+});