Unified preferred representation API + rename settings prefixes

- HDSModel-Preferred: getPreferredInput/getPreferredDisplay unified API
  for both variation items (kg/lb) and converter items (mood/mucus)
- Rename settings: converter-auto- → preferred-display-,
  converter-default- → preferred-input-
- Standalone getPreferredInput/getPreferredDisplay functions
- Variation resolution: per-item override → unitSystem fallback → default
- 12 new preferred API tests, 318 total passing

Author: perki

tests/HDSSettings.test.js

@@ -209,95 +209,95 @@ describe('[HDSD] HDSSettings dynamic settings', function () {
   });
 
   it('[HDSD1] _testInject and get work for dynamic keys', () => {
-    HDSSettings._testInject('converter-auto-wellbeing-mood', 'billings');
-    assert.strictEqual(HDSSettings.get('converter-auto-wellbeing-mood'), 'billings');
+    HDSSettings._testInject('preferred-display-wellbeing-mood', 'billings');
+    assert.strictEqual(HDSSettings.get('preferred-display-wellbeing-mood'), 'billings');
     assert.strictEqual(HDSSettings.isHooked, true);
   });
 
   it('[HDSD2] _testClear removes dynamic key', () => {
-    HDSSettings._testInject('converter-auto-wellbeing-mood', 'mira');
-    HDSSettings._testClear('converter-auto-wellbeing-mood');
-    assert.strictEqual(HDSSettings.get('converter-auto-wellbeing-mood'), undefined);
+    HDSSettings._testInject('preferred-display-wellbeing-mood', 'mira');
+    HDSSettings._testClear('preferred-display-wellbeing-mood');
+    assert.strictEqual(HDSSettings.get('preferred-display-wellbeing-mood'), undefined);
   });
 
   it('[HDSD3] getDynamic returns all settings with prefix', () => {
-    HDSSettings._testInject('converter-auto-wellbeing-mood', 'billings');
-    HDSSettings._testInject('converter-auto-body-vulva-mucus-inspect', 'appleHealth');
-    const all = HDSSettings.getDynamic('converter-auto-');
+    HDSSettings._testInject('preferred-display-wellbeing-mood', 'billings');
+    HDSSettings._testInject('preferred-display-body-vulva-mucus-inspect', 'appleHealth');
+    const all = HDSSettings.getDynamic('preferred-display-');
     assert.strictEqual(all['wellbeing-mood'], 'billings');
     assert.strictEqual(all['body-vulva-mucus-inspect'], 'appleHealth');
   });
 
   it('[HDSD4] unhook clears dynamic settings', () => {
-    HDSSettings._testInject('converter-auto-wellbeing-mood', 'billings');
+    HDSSettings._testInject('preferred-display-wellbeing-mood', 'billings');
     HDSSettings.unhook();
-    assert.strictEqual(HDSSettings.get('converter-auto-wellbeing-mood'), undefined);
-    assert.deepStrictEqual(HDSSettings.getDynamic('converter-auto-'), {});
+    assert.strictEqual(HDSSettings.get('preferred-display-wellbeing-mood'), undefined);
+    assert.deepStrictEqual(HDSSettings.getDynamic('preferred-display-'), {});
   });
 
   it('[HDSD5] load reads dynamic settings from server events', async () => {
     const conn = createMockConnection({
       'events.get': () => ({
         events: [
-          { id: 'ev-ac1', type: 'settings/converter-auto', content: { itemKey: 'wellbeing-mood', method: 'billings' } },
-          { id: 'ev-ac2', type: 'settings/converter-auto', content: { itemKey: 'body-vulva-mucus-inspect', method: 'appleHealth' } },
+          { id: 'ev-ac1', type: 'settings/preferred-display', content: { itemKey: 'wellbeing-mood', value: 'billings' } },
+          { id: 'ev-ac2', type: 'settings/preferred-display', content: { itemKey: 'body-vulva-mucus-inspect', value: 'appleHealth' } },
           { id: 'ev-t', type: 'settings/theme', content: 'dark' },
         ]
       })
     });
     await HDSSettings.hookToConnection(conn, 'test-stream');
-    assert.strictEqual(HDSSettings.get('converter-auto-wellbeing-mood'), 'billings');
-    assert.strictEqual(HDSSettings.get('converter-auto-body-vulva-mucus-inspect'), 'appleHealth');
+    assert.strictEqual(HDSSettings.get('preferred-display-wellbeing-mood'), 'billings');
+    assert.strictEqual(HDSSettings.get('preferred-display-body-vulva-mucus-inspect'), 'appleHealth');
     assert.strictEqual(HDSSettings.get('theme'), 'dark');
   });
 
   it('[HDSD6] setDynamic creates new event', async () => {
     const conn = createMockConnection();
     await HDSSettings.hookToConnection(conn, 'test-stream');
 
-    await HDSSettings.setDynamic('converter-auto-wellbeing-mood', 'billings');
-    assert.strictEqual(HDSSettings.get('converter-auto-wellbeing-mood'), 'billings');
+    await HDSSettings.setDynamic('preferred-display-wellbeing-mood', 'billings');
+    assert.strictEqual(HDSSettings.get('preferred-display-wellbeing-mood'), 'billings');
 
     const createCall = conn.apiCalls.find(c =>
-      c.method === 'events.create' && c.params.type === 'settings/converter-auto'
+      c.method === 'events.create' && c.params.type === 'settings/preferred-display'
     );
     assert.ok(createCall, 'Should have called events.create');
     assert.strictEqual(createCall.params.content.itemKey, 'wellbeing-mood');
-    assert.strictEqual(createCall.params.content.method, 'billings');
+    assert.strictEqual(createCall.params.content.value, 'billings');
   });
 
   it('[HDSD7] setDynamic updates existing event', async () => {
     const conn = createMockConnection({
       'events.get': () => ({
         events: [
-          { id: 'ev-ac-mood', type: 'settings/converter-auto', content: { itemKey: 'wellbeing-mood', method: 'billings' } }
+          { id: 'ev-ac-mood', type: 'settings/preferred-display', content: { itemKey: 'wellbeing-mood', value: 'billings' } }
         ]
       })
     });
     await HDSSettings.hookToConnection(conn, 'test-stream');
-    assert.strictEqual(HDSSettings.get('converter-auto-wellbeing-mood'), 'billings');
+    assert.strictEqual(HDSSettings.get('preferred-display-wellbeing-mood'), 'billings');
 
-    await HDSSettings.setDynamic('converter-auto-wellbeing-mood', 'mira');
-    assert.strictEqual(HDSSettings.get('converter-auto-wellbeing-mood'), 'mira');
+    await HDSSettings.setDynamic('preferred-display-wellbeing-mood', 'mira');
+    assert.strictEqual(HDSSettings.get('preferred-display-wellbeing-mood'), 'mira');
 
     const updateCall = conn.apiCalls.find(c => c.method === 'events.update');
     assert.ok(updateCall, 'Should have called events.update');
     assert.strictEqual(updateCall.params.id, 'ev-ac-mood');
-    assert.strictEqual(updateCall.params.update.content.method, 'mira');
+    assert.strictEqual(updateCall.params.update.content.value, 'mira');
   });
 
   it('[HDSD8] setDynamic with null deletes setting', async () => {
     const conn = createMockConnection({
       'events.get': () => ({
         events: [
-          { id: 'ev-ac-mood', type: 'settings/converter-auto', content: { itemKey: 'wellbeing-mood', method: 'billings' } }
+          { id: 'ev-ac-mood', type: 'settings/preferred-display', content: { itemKey: 'wellbeing-mood', value: 'billings' } }
         ]
       })
     });
     await HDSSettings.hookToConnection(conn, 'test-stream');
 
-    await HDSSettings.setDynamic('converter-auto-wellbeing-mood', null);
-    assert.strictEqual(HDSSettings.get('converter-auto-wellbeing-mood'), undefined);
+    await HDSSettings.setDynamic('preferred-display-wellbeing-mood', null);
+    assert.strictEqual(HDSSettings.get('preferred-display-wellbeing-mood'), undefined);
 
     const deleteCall = conn.apiCalls.find(c => c.method === 'events.delete');
     assert.ok(deleteCall, 'Should have called events.delete');
@@ -315,7 +315,7 @@ describe('[HDSD] HDSSettings dynamic settings', function () {
 
   it('[HDSD10] setDynamic throws when not hooked', async () => {
     await assert.rejects(
-      () => HDSSettings.setDynamic('converter-auto-wellbeing-mood', 'billings'),
+      () => HDSSettings.setDynamic('preferred-display-wellbeing-mood', 'billings'),
       /hookToApplication|hookToConnection/
     );
   });

tests/eventToShortText.test.js

@@ -419,14 +419,14 @@ describe('[ESTX] eventToShortText', () => {
     });
 
     it('[EST22b] autoConvert same method — shows sourceData + method name (no conversion)', async () => {
-      HDSSettings._testInject('converter-auto-wellbeing-mood', 'mira');
+      HDSSettings._testInject('preferred-display-wellbeing-mood', 'mira');
       const event = await model.converters.convertMethodToEvent('mood', 'mira', 'Happy');
       event.time = Date.now() / 1000;
       assert.equal(eventToShortText(event), 'Happy (Mira)');
     });
 
     it('[EST22c] autoConvert mood mira→hds — shows stop labels with target <- source', async () => {
-      HDSSettings._testInject('converter-auto-wellbeing-mood', 'hds');
+      HDSSettings._testInject('preferred-display-wellbeing-mood', 'hds');
       const event = await model.converters.convertMethodToEvent('mood', 'mira', 'Happy');
       event.time = Date.now() / 1000;
       const result = eventToShortText(event);
@@ -436,15 +436,15 @@ describe('[ESTX] eventToShortText', () => {
     });
 
     it('[EST22d] autoConvert cervical fluid mira→appleHealth — localized label + perfect match', async () => {
-      HDSSettings._testInject('converter-auto-body-vulva-mucus-inspect', 'appleHealth');
+      HDSSettings._testInject('preferred-display-body-vulva-mucus-inspect', 'appleHealth');
       const event = await model.converters.convertMethodToEvent('cervical-fluid', 'mira', 'Creamy');
       event.time = Date.now() / 1000;
       // "creamy" value should resolve to "Creamy" label from appleHealth method
       assert.equal(eventToShortText(event), 'Creamy (Apple Health <- Mira)');
     });
 
     it('[EST22e] autoConvert cervical fluid mira→billings — localized label + partial match', async () => {
-      HDSSettings._testInject('converter-auto-body-vulva-mucus-inspect', 'billings');
+      HDSSettings._testInject('preferred-display-body-vulva-mucus-inspect', 'billings');
       const event = await model.converters.convertMethodToEvent('cervical-fluid', 'mira', 'Watery');
       event.time = Date.now() / 1000;
       const result = eventToShortText(event);
@@ -455,7 +455,7 @@ describe('[ESTX] eventToShortText', () => {
     });
 
     it('[EST22f] autoConvert raw vector (no source) — shows result + target name', async () => {
-      HDSSettings._testInject('converter-auto-wellbeing-mood', 'mira');
+      HDSSettings._testInject('preferred-display-wellbeing-mood', 'mira');
       const event = {
         content: { vectors: { valence: 0.8, arousal: 0.2, dominance: 0.7, socialOrientation: 0.5, temporalFocus: 0.3 } },
         streamIds: ['wellbeing-mood'],
@@ -468,7 +468,7 @@ describe('[ESTX] eventToShortText', () => {
     });
 
     it('[EST22g] all cervical fluid mira→appleHealth labels are capitalized', async () => {
-      HDSSettings._testInject('converter-auto-body-vulva-mucus-inspect', 'appleHealth');
+      HDSSettings._testInject('preferred-display-body-vulva-mucus-inspect', 'appleHealth');
       const pairs = [
         ['No discharge', 'Dry'], ['Dry', 'Dry'], ['Sticky', 'Sticky'],
         ['Creamy', 'Creamy'], ['Watery', 'Watery'], ['Raw Egg White', 'Egg White'],

tests/preferred.test.js

@@ -0,0 +1,120 @@
+import { assert } from './test-utils/deps-node.js';
+import { HDSSettings } from '../ts/index.ts';
+import { getModel } from '../ts/HDSModel/HDSModelInitAndSingleton.ts';
+
+const modelURL = 'https://model.datasafe.dev/pack.json';
+
+describe('[PREF] HDSModel.preferred', function () {
+  let model;
+
+  before(async () => {
+    model = getModel();
+    await model.load(modelURL);
+    await model.converters.ensureEngine('mood');
+    await model.converters.ensureEngine('cervical-fluid');
+  });
+
+  afterEach(() => {
+    HDSSettings.unhook();
+  });
+
+  // ─── Variation items ─────────────────────────────────────────
+
+  describe('[PREF-V] variation items', () => {
+    it('[PREF-V1] body-weight returns variation config with default (metric)', () => {
+      HDSSettings._testInject('unitSystem', 'metric');
+      const pref = model.preferred.getPreferredInput('body-weight');
+      assert.equal(pref.type, 'variation');
+      assert.equal(pref.eventType, 'mass/kg');
+      assert.ok(pref.symbol, 'Should have symbol');
+    });
+
+    it('[PREF-V2] body-weight returns imperial when unitSystem=imperial', () => {
+      HDSSettings._testInject('unitSystem', 'imperial');
+      const pref = model.preferred.getPreferredInput('body-weight');
+      assert.equal(pref.type, 'variation');
+      assert.equal(pref.eventType, 'mass/lb');
+    });
+
+    it('[PREF-V3] per-item override takes precedence over unitSystem', () => {
+      HDSSettings._testInject('unitSystem', 'metric');
+      HDSSettings._testInject('preferred-input-body-weight', 'mass/lb');
+      const pref = model.preferred.getPreferredInput('body-weight');
+      assert.equal(pref.eventType, 'mass/lb');
+    });
+
+    it('[PREF-V4] body-height respects per-item override (Canada: metric but ft)', () => {
+      HDSSettings._testInject('unitSystem', 'metric');
+      HDSSettings._testInject('preferred-input-body-height', 'length/ft');
+      const weightPref = model.preferred.getPreferredInput('body-weight');
+      const heightPref = model.preferred.getPreferredInput('body-height');
+      assert.equal(weightPref.eventType, 'mass/kg', 'weight follows unitSystem');
+      assert.equal(heightPref.eventType, 'length/ft', 'height uses per-item override');
+    });
+
+    it('[PREF-V5] display and input can differ', () => {
+      HDSSettings._testInject('unitSystem', 'metric');
+      HDSSettings._testInject('preferred-display-body-weight', 'mass/lb');
+      const input = model.preferred.getPreferredInput('body-weight');
+      const display = model.preferred.getPreferredDisplay('body-weight');
+      assert.equal(input.eventType, 'mass/kg', 'input follows unitSystem');
+      assert.equal(display.eventType, 'mass/lb', 'display uses per-item override');
+    });
+
+    it('[PREF-V6] without settings returns first option as default', () => {
+      const pref = model.preferred.getPreferredInput('body-weight');
+      assert.equal(pref.type, 'variation');
+      assert.ok(pref.eventType, 'Should have an eventType');
+    });
+  });
+
+  // ─── Converter items ─────────────────────────────────────────
+
+  describe('[PREF-C] converter items', () => {
+    it('[PREF-C1] mood with no preference returns method=null', () => {
+      const pref = model.preferred.getPreferredInput('wellbeing-mood');
+      assert.equal(pref.type, 'converter');
+      assert.equal(pref.method, null);
+      assert.ok(pref.engine, 'Should have engine');
+    });
+
+    it('[PREF-C2] mood with preferred-input returns method + name', () => {
+      HDSSettings._testInject('preferred-input-wellbeing-mood', 'mira');
+      const pref = model.preferred.getPreferredInput('wellbeing-mood');
+      assert.equal(pref.type, 'converter');
+      assert.equal(pref.method, 'mira');
+      assert.equal(pref.methodName, 'Mira');
+    });
+
+    it('[PREF-C3] cervical-fluid preferred-display returns method', () => {
+      HDSSettings._testInject('preferred-display-body-vulva-mucus-inspect', 'appleHealth');
+      const pref = model.preferred.getPreferredDisplay('body-vulva-mucus-inspect');
+      assert.equal(pref.type, 'converter');
+      assert.equal(pref.method, 'appleHealth');
+      assert.equal(pref.methodName, 'Apple Health');
+    });
+
+    it('[PREF-C4] input and display can differ', () => {
+      HDSSettings._testInject('preferred-input-body-vulva-mucus-inspect', 'chartneo');
+      HDSSettings._testInject('preferred-display-body-vulva-mucus-inspect', 'billings');
+      const input = model.preferred.getPreferredInput('body-vulva-mucus-inspect');
+      const display = model.preferred.getPreferredDisplay('body-vulva-mucus-inspect');
+      assert.equal(input.method, 'chartneo');
+      assert.equal(display.method, 'billings');
+    });
+  });
+
+  // ─── Default items (no variation, no converter) ──────────────
+
+  describe('[PREF-D] default items', () => {
+    it('[PREF-D1] simple checkbox returns default', () => {
+      const pref = model.preferred.getPreferredInput('activity-yoga');
+      assert.equal(pref.type, 'default');
+    });
+
+    it('[PREF-D2] unknown item returns default', () => {
+      const pref = model.preferred.getPreferredInput('nonexistent-item');
+      assert.equal(pref.type, 'default');
+    });
+  });
+});