ui_bridge.js

const BRIDGE_MARKER = '__neptuneUiBridge__';

function isPlainRecord(value) {
    if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
    const prototype = Object.getPrototypeOf(value);
    return prototype === Object.prototype || prototype === null;
}

function clonePayload(value, seen = new WeakSet()) {
    if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
    if (typeof value === 'number') {
        if (!Number.isFinite(value)) throw new TypeError('UI payload numbers must be finite');
        return value;
    }
    if (typeof value !== 'object' || seen.has(value)) throw new TypeError('UI payload must contain only acyclic JSON data');
    if (!Array.isArray(value) && !isPlainRecord(value)) throw new TypeError('UI payload must contain only plain objects and arrays');
    seen.add(value);
    const result = Array.isArray(value)
        ? value.map(item => clonePayload(item, seen))
        : Object.fromEntries(Object.entries(value).map(([key, item]) => [key, clonePayload(item, seen)]));
    seen.delete(value);
    return result;
}

/**
 * Create a typed, serializable event bridge between the game runtime and an HTML UI.
 * Events use `{ type: 'neptune:ui', version: 1, direction, name, payload }`.
 * @param {object} options
 * @param {Window} [options.window] Window-like message target (defaults to globalThis.window).
 * @param {Window} [options.parent] Parent window accepted for incoming parent messages.
 * @param {string} [options.origin] Exact allowed parent origin; defaults to current origin.
 * @param {string} [options.targetOrigin] Exact destination origin; defaults to origin.
 * @param {string[]} [options.actions] Allowed UI-to-engine action names.
 * @returns {{subscribe: Function, emit: Function, onAction: Function, destroy: Function}}
 */
export function createUIBridge({ window: target = globalThis.window, parent = target?.parent, origin = target?.location?.origin, targetOrigin = origin, actions = [] } = {}) {
    if (!target || typeof target.addEventListener !== 'function' || typeof target.postMessage !== 'function') {
        throw new TypeError('UI bridge requires a window-like message target');
    }
    if (typeof origin !== 'string' || !origin || origin === 'null' || typeof targetOrigin !== 'string' || !targetOrigin || targetOrigin === '*') {
        throw new TypeError('UI bridge requires explicit non-opaque origin and targetOrigin values');
    }
    const allowedActions = new Set(actions);
    const subscriptions = new Map();
    let destroyed = false;
    const listener = event => {
        if (destroyed || event.source !== parent || event.origin !== origin) return;
        const message = event.data;
        if (!isPlainRecord(message) || message[BRIDGE_MARKER] !== true || message.version !== 1 || message.direction !== 'ui-to-engine' || typeof message.name !== 'string' || !allowedActions.has(message.name)) return;
        try {
            const payload = clonePayload(message.payload);
            for (const callback of subscriptions.get(message.name) || []) callback(payload);
            for (const callback of subscriptions.get('*') || []) callback(message.name, payload);
        } catch { /* Ignore malformed messages and errors from hostile payloads. */ }
    };
    target.addEventListener('message', listener);
    return {
        subscribe(name, callback) {
            if (destroyed) throw new Error('UI bridge has been destroyed');
            if (typeof name !== 'string' || !name || typeof callback !== 'function') throw new TypeError('subscribe requires an event name and callback');
            const set = subscriptions.get(name) || new Set();
            set.add(callback);
            subscriptions.set(name, set);
            return () => { set.delete(callback); if (set.size === 0) subscriptions.delete(name); };
        },
        onAction(name, callback) {
            if (!allowedActions.has(name)) throw new TypeError(`UI action is not allowed: ${name}`);
            return this.subscribe(name, callback);
        },
        emit(name, payload = null) {
            if (destroyed) throw new Error('UI bridge has been destroyed');
            if (typeof name !== 'string' || !name) throw new TypeError('UI event name must be a non-empty string');
            const data = clonePayload(payload);
            parent.postMessage({ [BRIDGE_MARKER]: true, version: 1, direction: 'engine-to-ui', name, payload: data }, targetOrigin);
        },
        destroy() {
            if (destroyed) return;
            destroyed = true;
            target.removeEventListener('message', listener);
            subscriptions.clear();
        }
    };
}

/** Build the browser-side HTML UI client, exposing only explicitly allowed actions. */
export function createHTMLUIClient({ window: target = globalThis.window, actions = [], events = [] } = {}) {
    if (!target || typeof target.addEventListener !== 'function' || typeof target.removeEventListener !== 'function') throw new TypeError('HTML UI client requires a window with message event support');
    const origin = target.location?.origin;
    if (typeof origin !== 'string' || !origin || origin === 'null') throw new TypeError('HTML UI client requires a non-opaque origin');
    const parentWindow = target.parent;
    if (!parentWindow || typeof parentWindow.postMessage !== 'function') throw new TypeError('HTML UI client requires a window with a parent');
    const allowedActions = new Set(actions);
    const allowedEvents = new Set(events);
    const listeners = new Map();
    let destroyed = false;
    const listener = event => {
        const message = event.data;
        if (destroyed || event.source !== target.parent || event.origin !== origin || !isPlainRecord(message) || message[BRIDGE_MARKER] !== true || message.version !== 1 || message.direction !== 'engine-to-ui' || !allowedEvents.has(message.name)) return;
        try {
            const payload = clonePayload(message.payload);
            for (const callback of listeners.get(message.name) || []) callback(payload);
            for (const callback of listeners.get('*') || []) callback(message.name, payload);
        } catch { /* Ignore malformed messages and listener errors. */ }
    };
    target.addEventListener('message', listener);
    return {
        emit(name, payload = null) {
            if (destroyed) throw new Error('HTML UI client has been destroyed');
            if (!allowedActions.has(name)) throw new TypeError(`UI action is not allowed: ${name}`);
            target.parent.postMessage({ [BRIDGE_MARKER]: true, version: 1, direction: 'ui-to-engine', name, payload: clonePayload(payload) }, origin);
        },
        on(name, callback) {
            if (destroyed) throw new Error('HTML UI client has been destroyed');
            if (typeof name !== 'string' || !name || typeof callback !== 'function') throw new TypeError('on requires an event name and callback');
            const set = listeners.get(name) || new Set();
            set.add(callback);
            listeners.set(name, set);
            return () => { set.delete(callback); if (!set.size) listeners.delete(name); };
        },
        destroy() {
            if (destroyed) return;
            destroyed = true;
            target.removeEventListener('message', listener);
            listeners.clear();
        }
    };
}

/**
 * Attach focus-based keyboard/controller navigation to a UI root. The injected
 * adapter can translate gamepad buttons to the same directional commands.
 * @param {Element} root
 * @param {Object} options Navigation callbacks and optional controller adapter.
 * @returns {Function} cleanup callback
 */
export function installUINavigation(root, { onNavigate = () => {}, onActivate = () => {}, gamepad } = {}) {
    if (!root || typeof root.addEventListener !== 'function' || typeof root.querySelectorAll !== 'function') throw new TypeError('Navigation requires a DOM root');
    const selector = '[data-neptune-nav], button:not([disabled]), a[href], input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
    const items = () => [...root.querySelectorAll(selector)].filter(item => !item.hidden && item.getAttribute('aria-hidden') !== 'true');
    const handler = event => {
        const controls = items();
        const current = controls.indexOf(root.ownerDocument?.activeElement);
        const direction = { ArrowDown: 1, ArrowRight: 1, ArrowUp: -1, ArrowLeft: -1 }[event.key];
        if (direction !== undefined && controls.length) {
            event.preventDefault();
            const next = (current + direction + controls.length) % controls.length;
            controls[next].focus();
            onNavigate({ index: next, element: controls[next], direction });
        } else if ((event.key === 'Enter' || event.key === ' ') && current >= 0) {
            onActivate({ index: current, element: controls[current] });
        }
    };
    root.addEventListener('keydown', handler);
    const stop = typeof gamepad === 'function' ? gamepad(command => {
        const key = { up: 'ArrowUp', down: 'ArrowDown', left: 'ArrowLeft', right: 'ArrowRight', activate: 'Enter' }[command];
        if (key) handler({ key, preventDefault() {} });
    }) : null;
    return () => { root.removeEventListener('keydown', handler); if (typeof stop === 'function') stop(); };
}

/** Create a ready-to-use `window.neptuneUI` client for an embedded HTML interface. */
export function installHTMLUI({ window: target = globalThis.window, actions = [], events = [] } = {}) {
    if (!target || target[BRIDGE_MARKER]) throw new Error('Neptune UI bridge is already installed or has no window');
    const client = createHTMLUIClient({ window: target, actions, events });
    Object.defineProperty(target, 'neptuneUI', { configurable: true, value: client });
    Object.defineProperty(target, BRIDGE_MARKER, { configurable: true, value: client });
    return client;
}