brep-io-kernel 1.0.17 → 1.0.19

package/src/UI/SelectionFilter.js

@@ -17,6 +17,15 @@ export class SelectionFilter {
     static previouseAllowedSelectionTypes = null;
     static _hovered = new Set(); // objects currently hover-highlighted
     static hoverColor = '#fbff00'; // default hover tint
+    static _selectionActions = new Map();
+    static _selectionActionOrder = [];
+    static _selectionActionSeq = 1;
+    static _selectionActionListenerBound = false;
+    static _selectionActionsPending = false;
+    static _selectionActionBar = null;
+    static _historyContextActions = new Map();
+    static _selectionActionSeparator = null;
+    static _contextSuppressReasons = new Set();
 
     constructor() {
         throw new Error("SelectionFilter is static and cannot be instantiated.");
@@ -188,6 +197,25 @@ export class SelectionFilter {
             let clone;
             try { clone = typeof origMat.clone === 'function' ? origMat.clone() : origMat; } catch { clone = origMat; }
             try { if (clone && clone.color && typeof clone.color.set === 'function') clone.color.set(SelectionFilter.hoverColor); } catch { }
+            try {
+                if (origMat && clone && origMat.resolution && clone.resolution && typeof clone.resolution.copy === 'function') {
+                    clone.resolution.copy(origMat.resolution);
+                }
+            } catch { }
+            try {
+                if (origMat && clone && typeof origMat.dashed !== 'undefined' && typeof clone.dashed !== 'undefined') {
+                    clone.dashed = origMat.dashed;
+                }
+                if (origMat && clone && typeof origMat.dashSize !== 'undefined' && typeof clone.dashSize !== 'undefined') {
+                    clone.dashSize = origMat.dashSize;
+                }
+                if (origMat && clone && typeof origMat.gapSize !== 'undefined' && typeof clone.gapSize !== 'undefined') {
+                    clone.gapSize = origMat.gapSize;
+                }
+                if (origMat && clone && typeof origMat.dashScale !== 'undefined' && typeof clone.dashScale !== 'undefined') {
+                    clone.dashScale = origMat.dashScale;
+                }
+            } catch { }
             try {
                 t.userData.__hoverOrigMat = origMat;
                 t.userData.__hoverMatApplied = true;
@@ -429,6 +457,11 @@ export class SelectionFilter {
                 if (!targetObj) return false;
 
                 // Update the reference input with the chosen object
+                try {
+                    if (activeRefInput && typeof activeRefInput.__captureReferencePreview === 'function') {
+                        activeRefInput.__captureReferencePreview(targetObj);
+                    }
+                } catch (_) { /* ignore preview capture errors */ }
                 const objType = targetObj.type;
                 const objectName = targetObj.name || `${objType}(${targetObj.position?.x || 0},${targetObj.position?.y || 0},${targetObj.position?.z || 0})`;
 
@@ -617,6 +650,411 @@ export class SelectionFilter {
         } catch (_) { /* noop */ }
     }
 
+    static getSelectedObjects(options = {}) {
+        const scene = options.scene
+            || SelectionFilter.viewer?.partHistory?.scene
+            || SelectionFilter.viewer?.scene
+            || null;
+        const selected = [];
+        if (!scene || typeof scene.traverse !== 'function') return selected;
+        scene.traverse((obj) => {
+            if (obj && obj.selected) selected.push(obj);
+        });
+        return selected;
+    }
+
+    static registerSelectionAction(spec = {}) {
+        if (!spec) return null;
+        const id = String(spec.id || `selection-action-${SelectionFilter._selectionActionSeq++}`);
+        const entry = SelectionFilter._selectionActions.get(id) || { id };
+        entry.label = spec.label ?? entry.label ?? '';
+        entry.title = spec.title ?? entry.title ?? entry.label ?? '';
+        entry.onClick = spec.onClick ?? entry.onClick ?? null;
+        entry.shouldShow = typeof spec.shouldShow === 'function' ? spec.shouldShow : (entry.shouldShow || null);
+        SelectionFilter._selectionActions.set(id, entry);
+        if (!SelectionFilter._selectionActionOrder.includes(id)) {
+            SelectionFilter._selectionActionOrder.push(id);
+        }
+        SelectionFilter._ensureSelectionActionListener();
+        SelectionFilter._syncSelectionActions();
+        return id;
+    }
+
+    static unregisterSelectionAction(id) {
+        if (!id) return;
+        const entry = SelectionFilter._selectionActions.get(id);
+        if (entry?.btn && entry.btn.parentNode) {
+            try { entry.btn.parentNode.removeChild(entry.btn); } catch { }
+        }
+        SelectionFilter._selectionActions.delete(id);
+        SelectionFilter._selectionActionOrder = SelectionFilter._selectionActionOrder.filter((k) => k !== id);
+        SelectionFilter._syncSelectionActions();
+    }
+
+    static refreshSelectionActions() {
+        SelectionFilter._syncSelectionActions();
+    }
+
+    static _ensureSelectionActionListener() {
+        if (SelectionFilter._selectionActionListenerBound) return;
+        if (typeof window === 'undefined') return;
+        SelectionFilter._selectionActionListenerBound = true;
+        window.addEventListener('selection-changed', () => SelectionFilter._syncSelectionActions());
+    }
+
+    static _syncSelectionActions() {
+        const viewer = SelectionFilter.viewer;
+        const bar = SelectionFilter._ensureSelectionActionBar(viewer);
+        if (!bar) {
+            SelectionFilter._selectionActionsPending = true;
+            return;
+        }
+        SelectionFilter._selectionActionsPending = false;
+        const suppressed = SelectionFilter._contextSuppressReasons?.size > 0;
+        if (suppressed) {
+            try { bar.style.display = 'none'; } catch { }
+            return;
+        }
+        const selection = SelectionFilter.getSelectedObjects();
+        const hideAll = !!viewer?._sketchMode;
+        const utilityButtons = [];
+        const actions = SelectionFilter._selectionActions;
+
+        for (const id of SelectionFilter._selectionActionOrder) {
+            const entry = actions.get(id);
+            if (!entry) continue;
+            if (!entry.btn) {
+                entry.btn = SelectionFilter._createSelectionActionButton(entry);
+            }
+            if (!entry.btn) continue;
+            try {
+                entry.btn.textContent = String(entry.label ?? '');
+                entry.btn.title = String(entry.title ?? entry.label ?? '');
+                entry.btn.__sabOnClick = entry.onClick;
+                const isIcon = String(entry.label || '').length <= 2;
+                entry.btn.classList.toggle('sab-icon', isIcon);
+            } catch { }
+            let show = !hideAll;
+            if (show) {
+                if (typeof entry.shouldShow === 'function') {
+                    try { show = !!entry.shouldShow(selection, viewer); } catch { show = false; }
+                } else {
+                    show = selection.length > 0;
+                }
+            }
+            if (show) utilityButtons.push(entry.btn);
+        }
+
+        const historySpecs = SelectionFilter._getHistoryContextActionSpecs(selection, viewer);
+        const contextButtons = [];
+        const desiredIds = new Set();
+        for (const spec of historySpecs) {
+            if (!spec || !spec.id) continue;
+            desiredIds.add(spec.id);
+            const existing = SelectionFilter._historyContextActions.get(spec.id) || { id: spec.id };
+            existing.label = spec.label ?? existing.label ?? '';
+            existing.title = spec.title ?? existing.title ?? existing.label ?? '';
+            existing.onClick = spec.onClick ?? existing.onClick ?? null;
+            existing.shouldShow = typeof spec.shouldShow === 'function' ? spec.shouldShow : null;
+            if (!existing.btn) {
+                existing.btn = SelectionFilter._createSelectionActionButton(existing);
+            }
+            if (!existing.btn) continue;
+            try {
+                existing.btn.textContent = String(existing.label ?? '');
+                existing.btn.title = String(existing.title ?? existing.label ?? '');
+                existing.btn.__sabOnClick = existing.onClick;
+                const isIcon = String(existing.label || '').length <= 2;
+                existing.btn.classList.toggle('sab-icon', isIcon);
+            } catch { }
+            let show = !hideAll;
+            if (show && typeof existing.shouldShow === 'function') {
+                try { show = !!existing.shouldShow(selection, viewer); } catch { show = false; }
+            } else if (!existing.shouldShow) {
+                show = show && selection.length > 0;
+            }
+            if (show) contextButtons.push(existing.btn);
+            SelectionFilter._historyContextActions.set(spec.id, existing);
+        }
+
+        for (const [id, entry] of SelectionFilter._historyContextActions.entries()) {
+            if (desiredIds.has(id)) continue;
+            try { entry.btn?.remove?.(); } catch { }
+            SelectionFilter._historyContextActions.delete(id);
+        }
+
+        try { bar.textContent = ''; } catch { }
+        for (const btn of utilityButtons) {
+            try { bar.appendChild(btn); } catch { }
+        }
+        if (utilityButtons.length && contextButtons.length) {
+            const sep = SelectionFilter._ensureSelectionActionSeparator();
+            if (sep) {
+                try { bar.appendChild(sep); } catch { }
+            }
+        }
+        for (const btn of contextButtons) {
+            try { bar.appendChild(btn); } catch { }
+        }
+        try { bar.style.display = (utilityButtons.length + contextButtons.length) > 0 ? 'flex' : 'none'; } catch { }
+    }
+
+    static _getHistoryContextActionSpecs(selection, viewer) {
+        const out = [];
+        const items = Array.isArray(selection) ? selection : [];
+        const safeId = (prefix, key) => {
+            const raw = String(key || '').toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
+            return `${prefix}-${raw || 'item'}`;
+        };
+        const addSpec = (spec) => {
+            if (spec && spec.id) out.push(spec);
+        };
+
+        const featureRegistry = viewer?.partHistory?.featureRegistry || null;
+        const features = Array.isArray(featureRegistry?.features) ? featureRegistry.features : [];
+        for (const FeatureClass of features) {
+            if (!FeatureClass) continue;
+            let result = null;
+            try { result = FeatureClass.showContexButton?.(items); } catch { result = null; }
+            if (!result) continue;
+            if (result && typeof result === 'object' && result.show === false) continue;
+            const label = (result && typeof result === 'object' && result.label) || FeatureClass.longName || FeatureClass.shortName || FeatureClass.name || 'Feature';
+            const typeKey = FeatureClass.shortName || FeatureClass.type || FeatureClass.name || label;
+            const params = SelectionFilter._extractContextParams(result);
+            addSpec({
+                id: safeId('ctx-feature', typeKey),
+                label,
+                title: `Create ${label}`,
+                onClick: () => SelectionFilter._createFeatureFromContext(viewer, typeKey, params),
+            });
+        }
+
+        const constraintRegistry = viewer?.partHistory?.assemblyConstraintRegistry || null;
+        const constraintClasses = typeof constraintRegistry?.listAvailable === 'function'
+            ? constraintRegistry.listAvailable()
+            : (typeof constraintRegistry?.list === 'function' ? constraintRegistry.list() : []);
+        if (Array.isArray(constraintClasses)) {
+            for (const ConstraintClass of constraintClasses) {
+                if (!ConstraintClass) continue;
+                let result = null;
+                try { result = ConstraintClass.showContexButton?.(items); } catch { result = null; }
+                if (!result) continue;
+                if (result && typeof result === 'object' && result.show === false) continue;
+                const label = (result && typeof result === 'object' && result.label) || ConstraintClass.longName || ConstraintClass.shortName || ConstraintClass.name || 'Constraint';
+                const typeKey = ConstraintClass.constraintType || ConstraintClass.shortName || ConstraintClass.name || label;
+                const params = SelectionFilter._extractContextParams(result);
+                addSpec({
+                    id: safeId('ctx-constraint', typeKey),
+                    label,
+                    title: `Create ${label}`,
+                    onClick: () => SelectionFilter._createConstraintFromContext(viewer, typeKey, params),
+                });
+            }
+        }
+
+        const pmimode = viewer?._pmiMode || null;
+        const annotationRegistry = viewer?.annotationRegistry || null;
+        if (pmimode && annotationRegistry && typeof annotationRegistry.list === 'function') {
+            const annClasses = annotationRegistry.list();
+            for (const AnnClass of annClasses) {
+                if (!AnnClass) continue;
+                let result = null;
+                try { result = AnnClass.showContexButton?.(items); } catch { result = null; }
+                if (!result) continue;
+                if (result && typeof result === 'object' && result.show === false) continue;
+                const label = (result && typeof result === 'object' && result.label) || AnnClass.longName || AnnClass.shortName || AnnClass.name || 'Annotation';
+                const typeKey = AnnClass.type || AnnClass.entityType || AnnClass.shortName || AnnClass.name || label;
+                const params = SelectionFilter._extractContextParams(result);
+                addSpec({
+                    id: safeId('ctx-annotation', typeKey),
+                    label,
+                    title: `Create ${label}`,
+                    onClick: () => SelectionFilter._createAnnotationFromContext(viewer, typeKey, params),
+                });
+            }
+        }
+
+        return out;
+    }
+
+    static async _createFeatureFromContext(viewer, typeKey, params = null) {
+        if (!viewer || !typeKey) return;
+        SelectionFilter.setContextBarSuppressed('context-create', true);
+        setTimeout(() => SelectionFilter.setContextBarSuppressed('context-create', false), 0);
+        let entry = null;
+        if (viewer.historyWidget && typeof viewer.historyWidget._handleAddEntry === 'function') {
+            try { entry = await viewer.historyWidget._handleAddEntry(typeKey); } catch { }
+        } else {
+            try { entry = await viewer.partHistory?.newFeature?.(typeKey); } catch { }
+        }
+        if (entry && params && typeof params === 'object') {
+            SelectionFilter._applyContextParamsToEntry(viewer, entry, params);
+        }
+        return entry;
+    }
+
+    static _createConstraintFromContext(viewer, typeKey, params = null) {
+        if (!viewer || !typeKey) return;
+        SelectionFilter.setContextBarSuppressed('context-create', true);
+        setTimeout(() => SelectionFilter.setContextBarSuppressed('context-create', false), 0);
+        try { viewer.partHistory?.assemblyConstraintHistory?.addConstraint?.(typeKey, params || null); } catch { }
+    }
+
+    static _createAnnotationFromContext(viewer, typeKey, params = null) {
+        if (!viewer || !typeKey) return;
+        SelectionFilter.setContextBarSuppressed('context-create', true);
+        setTimeout(() => SelectionFilter.setContextBarSuppressed('context-create', false), 0);
+        try { viewer._pmiMode?._annotationHistory?.createAnnotation?.(typeKey, params || null); } catch { }
+    }
+
+    static _extractContextParams(result) {
+        if (!result || result === true) return null;
+        if (typeof result !== 'object') return null;
+        if (result.params && typeof result.params === 'object') return result.params;
+        if (result.field) {
+            return { [result.field]: result.value };
+        }
+        return null;
+    }
+
+    static _applyContextParamsToEntry(viewer, entry, params = {}) {
+        if (!entry || !params || typeof params !== 'object') return;
+        try {
+            for (const [key, value] of Object.entries(params)) {
+                entry.inputParams = entry.inputParams || {};
+                entry.inputParams[key] = value;
+            }
+        } catch { }
+        const historyWidget = viewer?.historyWidget || null;
+        if (!historyWidget || typeof historyWidget._handleSchemaChange !== 'function') return;
+        try {
+            const id = entry?.inputParams?.id ?? entry?.id ?? null;
+            const entryId = String(id ?? '');
+            historyWidget._handleSchemaChange(entryId, entry, { key: '__context', value: params });
+            const refresh = () => {
+                try {
+                    const form = historyWidget.getFormForEntry?.(entryId);
+                    if (form && typeof form.refreshFromParams === 'function') {
+                        form.refreshFromParams();
+                        return true;
+                    }
+                } catch { }
+                return false;
+            };
+            if (!refresh()) {
+                setTimeout(() => { try { refresh(); } catch { } }, 0);
+            }
+        } catch { }
+    }
+
+    static setContextBarSuppressed(key, active) {
+        if (!key) return;
+        const reasons = SelectionFilter._contextSuppressReasons || new Set();
+        SelectionFilter._contextSuppressReasons = reasons;
+        const had = reasons.has(key);
+        if (active) {
+            reasons.add(key);
+        } else {
+            reasons.delete(key);
+        }
+        if (had !== reasons.has(key)) {
+            SelectionFilter._syncSelectionActions();
+        }
+    }
+
+    static _ensureSelectionActionSeparator() {
+        if (SelectionFilter._selectionActionSeparator && SelectionFilter._selectionActionSeparator.isConnected) {
+            return SelectionFilter._selectionActionSeparator;
+        }
+        if (typeof document === 'undefined') return null;
+        const el = document.createElement('div');
+        el.className = 'selection-action-sep';
+        SelectionFilter._selectionActionSeparator = el;
+        return el;
+    }
+
+    static _ensureSelectionActionBar(viewer) {
+        if (SelectionFilter._selectionActionBar && SelectionFilter._selectionActionBar.isConnected) {
+            return SelectionFilter._selectionActionBar;
+        }
+        if (typeof document === 'undefined') return null;
+        const host = viewer?.container || document.body || null;
+        if (!host) return null;
+        try {
+            if (!document.getElementById('selection-action-bar-styles')) {
+                const style = document.createElement('style');
+                style.id = 'selection-action-bar-styles';
+                style.textContent = `
+                  .selection-action-bar {
+                    position: absolute;
+                    top: 100px;
+                    right: 8px;
+                    display: flex;
+                    flex-direction: column;
+                    gap: 6px;
+                    align-items: stretch;
+                    background: rgba(20,24,30,.85);
+                    border: 1px solid #262b36;
+                    border-radius: 8px;
+                    padding: 6px;
+                    color: #ddd;
+                    min-width: 40px;
+                    max-width: 150px;
+                    z-index: 12;
+                    user-select: none;
+                  }
+                  .selection-action-bar .sab-btn {
+                    background: transparent;
+                    border-radius: 6px;
+                    padding: 4px 8px;
+                    width: 100%;
+                    min-height: 34px;
+                    box-sizing: border-box;
+                    color: #ddd;
+                    border: 1px solid #364053;
+                    cursor: pointer;
+                  }
+                  .selection-action-bar .sab-btn:hover { filter: brightness(1.08); }
+                  .selection-action-bar .sab-btn:active { filter: brightness(1.15); }
+                  .selection-action-bar .sab-btn.sab-icon {
+                    font-size: 16px;
+                    min-width: 36px;
+                  }
+                  .selection-action-bar .selection-action-sep {
+                    height: 1px;
+                    width: 100%;
+                    background: #2c3443;
+                    opacity: 0.9;
+                    margin: 4px 0;
+                  }
+                `;
+                document.head.appendChild(style);
+            }
+        } catch { }
+        const bar = document.createElement('div');
+        bar.className = 'selection-action-bar';
+        host.appendChild(bar);
+        SelectionFilter._selectionActionBar = bar;
+        return bar;
+    }
+
+    static _createSelectionActionButton(entry) {
+        try {
+            const btn = document.createElement('button');
+            btn.className = 'sab-btn';
+            btn.textContent = String(entry?.label ?? '');
+            btn.title = String(entry?.title ?? entry?.label ?? '');
+            btn.__sabOnClick = entry?.onClick ?? null;
+            btn.addEventListener('click', (e) => {
+                e.stopPropagation();
+                try { btn.__sabOnClick && btn.__sabOnClick(); } catch { }
+            });
+            const isIcon = String(entry?.label || '').length <= 2;
+            if (isIcon) btn.classList.add('sab-icon');
+            return btn;
+        } catch { return null; }
+    }
+
     static #logAllowedTypesChange(next, reason = '') {
         try {
             const desc = next === SelectionFilter.ALL

package/src/UI/featureDialogWidgets/booleanOperationField.js

@@ -1,9 +1,11 @@
+import { renderReferenceSelectionField } from './referenceSelectionField.js';
+
 export function renderBooleanOperationField({ ui, key, def, controlWrap }) {
     if (!ui.params[key] || typeof ui.params[key] !== 'object') {
-        ui.params[key] = { targets: [], operation: 'NONE', operation: 'NONE' };
+        ui.params[key] = { targets: [], operation: 'NONE' };
     } else {
         if (!Array.isArray(ui.params[key].targets)) ui.params[key].targets = [];
-        if (!ui.params[key].operation && !ui.params[key].operation) ui.params[key].operation = 'NONE';
+        if (!ui.params[key].operation) ui.params[key].operation = 'NONE';
     }
 
     const wrap = document.createElement('div');
@@ -19,70 +21,49 @@ export function renderBooleanOperationField({ ui, key, def, controlWrap }) {
         opt.textContent = String(op);
         sel.appendChild(opt);
     }
-    sel.value = String((ui.params[key].operation ?? ui.params[key].operation) || 'NONE');
+    sel.value = String(ui.params[key].operation || 'NONE');
     sel.addEventListener('change', () => {
         if (!ui.params[key] || typeof ui.params[key] !== 'object') ui.params[key] = { targets: [], operation: 'NONE' };
         ui.params[key].operation = sel.value;
-        ui.params[key].operation = sel.value;
         ui._emitParamsChange(key, ui.params[key]);
     });
     wrap.appendChild(sel);
 
-    const refWrap = document.createElement('div');
-    refWrap.className = 'ref-multi-wrap';
-    const chipsWrap = document.createElement('div');
-    chipsWrap.className = 'ref-chips';
-    refWrap.appendChild(chipsWrap);
-
-    const inputElTargets = document.createElement('input');
-    inputElTargets.type = 'text';
-    inputElTargets.className = 'input';
-    inputElTargets.dataset.multiple = 'true';
-    inputElTargets.placeholder = 'Click then select solids…';
-    ui._renderChips(chipsWrap, key, Array.isArray(ui.params[key].targets) ? ui.params[key].targets : []);
-
-    const activate = () => {
-        ui._activateReferenceSelection(inputElTargets, { selectionFilter: ['SOLID'] });
+    const refMount = document.createElement('div');
+    const targetsDef = {
+        type: 'reference_selection',
+        multiple: true,
+        selectionFilter: ['SOLID'],
     };
-    chipsWrap.addEventListener('click', activate);
-    inputElTargets.addEventListener('click', activate);
-
-    inputElTargets.addEventListener('change', () => {
-        if (inputElTargets.dataset && inputElTargets.dataset.forceClear === 'true') {
-            if (!ui.params[key] || typeof ui.params[key] !== 'object') ui.params[key] = { targets: [], operation: 'NONE' };
-            ui.params[key].targets = [];
-            ui._renderChips(chipsWrap, key, ui.params[key].targets);
-            inputElTargets.value = '';
-            delete inputElTargets.dataset.forceClear;
+    const valueAdapter = {
+        read: () => {
+            const current = ui.params[key];
+            if (!current || typeof current !== 'object') return [];
+            return Array.isArray(current.targets) ? current.targets : [];
+        },
+        write: (next) => {
+            if (!ui.params[key] || typeof ui.params[key] !== 'object') ui.params[key] = { targets: [], operation: sel.value || 'NONE' };
+            ui.params[key].targets = Array.isArray(next) ? next : [];
+        },
+        emit: () => {
             ui._emitParamsChange(key, ui.params[key]);
-            return;
-        }
-        if (!ui.params[key] || typeof ui.params[key] !== 'object') ui.params[key] = { targets: [], operation: 'NONE' };
-        let incoming = [];
-        try {
-            const parsed = JSON.parse(inputElTargets.value);
-            if (Array.isArray(parsed)) incoming = parsed;
-        } catch (_) {
-            if (inputElTargets.value && String(inputElTargets.value).trim() !== '') incoming = [String(inputElTargets.value).trim()];
-        }
-        const cur = Array.isArray(ui.params[key].targets) ? ui.params[key].targets : [];
-        for (const name of incoming) {
-            if (!cur.includes(name)) cur.push(name);
-        }
-        ui.params[key].targets = cur;
-        ui._renderChips(chipsWrap, key, cur);
-        inputElTargets.value = '';
-        ui._emitParamsChange(key, ui.params[key]);
+        },
+    };
+    const refField = renderReferenceSelectionField({
+        ui,
+        key,
+        def: targetsDef,
+        id: `${key}-targets`,
+        controlWrap: refMount,
+        valueAdapter,
     });
-
-    refWrap.appendChild(inputElTargets);
-    wrap.appendChild(refWrap);
+    wrap.appendChild(refMount);
 
     controlWrap.appendChild(wrap);
 
     return {
-        inputEl: inputElTargets,
-        activate,
+        inputEl: refField.inputEl,
+        activate: refField.activate,
         readValue() {
             const current = ui.params[key];
             if (!current || typeof current !== 'object') {

package/src/UI/featureDialogWidgets/referenceSelectionField.js

@@ -5,6 +5,7 @@ export function renderReferenceSelectionField({ ui, key, def, id, controlWrap, v
     inputEl.type = 'hidden';
     inputEl.id = id;
     try { inputEl.dataset.key = String(key); } catch (_) { }
+    try { inputEl.__refSelectionDef = def; } catch (_) { }
 
     const isMulti = !!def.multiple;
     if (isMulti) inputEl.dataset.multiple = 'true';
@@ -132,6 +133,15 @@ export function renderReferenceSelectionField({ ui, key, def, id, controlWrap, v
         inputEl.value = initial ?? '';
 
         valueWrap.addEventListener('click', () => ui._activateReferenceSelection(inputEl, def));
+        valueWrap.addEventListener('mouseenter', () => {
+            const normalized = normalizeReferenceName(inputEl.value || readRawValue());
+            if (normalized) {
+                try { ui._hoverReferenceSelectionItem?.(inputEl, def, normalized); } catch (_) { }
+            }
+        });
+        valueWrap.addEventListener('mouseleave', () => {
+            try { ui._clearReferenceSelectionHover?.(inputEl); } catch (_) { }
+        });
         refWrap.appendChild(valueWrap);
 
         inputEl.addEventListener('change', () => {