@zeyos/zx 3.0.0 → 4.0.0

package/src/{components/app-rail → internal}/app-rail.js

@@ -1,24 +1,24 @@
-import { Component } from '../../core/component.js';
-import { h } from '../../core/dom.js';
-import { icon } from '../../core/icons.js';
-import { Dropdown } from '../dropdown/dropdown.js';
-import { Tooltip } from '../tooltip/tooltip.js';
+import { Component } from '../core/component.js';
+import { h, safeHref } from '../core/dom.js';
+import { icon } from '../core/icons.js';
+import { Dropdown } from '../components/dropdown/dropdown.js';
+import { Tooltip } from '../components/tooltip/tooltip.js';
 
 /**
  * @typedef {Object} AppNavItem
  * @property {string|number} id Stable item identifier.
  * @property {string} label Visible/accessibility label.
- * @property {string} [icon] Kernel icon name.
+ * @property {string|Node|{toElement: () => Node|null}|((context: Record<string, any>, item: AppNavItem) => Node|null)} [icon] Icon name, node, component, or factory.
  * @property {string|number} [badge] Count or status badge.
  * @property {unknown} [value] Emitted value; defaults to `id`.
- * @property {string} [href] Native navigation target.
+ * @property {string} [href] Native navigation target; executable/data schemes are disabled.
  * @property {string} [target] Native link browsing context.
  * @property {() => void} [invoke] Application-owned non-link action.
  * @property {boolean} [disabled] Whether activation is unavailable.
  * @property {AppNavItem[]} [children] Child destinations/actions.
  */
 /**
- * @typedef {Object} AppRailOptions
+ * @typedef {Object} AppRailPresenterOptions
  * @property {AppNavItem[]} [items=[]] Application navigation tree.
  * @property {string|number|null} [active=null] Active item id.
  * @property {'vertical'|'horizontal'} [orientation='vertical'] Rail flow.
@@ -28,6 +28,7 @@ import { Tooltip } from '../tooltip/tooltip.js';
  * @property {Node|string|number|{toElement: () => Node|null}|null} [footer=null] Trailing rail content.
  * @property {number} [openDelay=80] Hover-open delay in milliseconds.
  * @property {number} [closeDelay=160] Pointer/focus crossing grace in milliseconds.
+ * @property {(item: AppNavItem, context: Record<string, any>) => Node|null} [renderIcon] Optional host icon renderer.
  * @property {(event: CustomEvent<AppNavSelectDetail>) => void} [onselect] Preventable action listener.
  * @property {(event: CustomEvent<{item: AppNavItem, id: string|number, open: boolean}>) => void} [onflyoutchange] Flyout-state listener.
  */
@@ -36,14 +37,14 @@ import { Tooltip } from '../tooltip/tooltip.js';
 
 /**
  * Minimized application navigation; descendants always open in hover/focus flyouts, never inline.
- * @fires AppRail#select
- * @fires AppRail#flyoutchange
- * @extends {Component<AppRailOptions>}
+ * @fires AppRailPresenter#select
+ * @fires AppRailPresenter#flyoutchange
+ * @extends {Component<AppRailPresenterOptions>}
  */
-export class AppRail extends Component {
+export class AppRailPresenter extends Component {
   static cssName = 'app-rail';
 
-  /** @type {Readonly<AppRailOptions>} */
+  /** @type {Readonly<AppRailPresenterOptions>} */
   static defaults = {
     items: [],
     active: null,
@@ -53,13 +54,14 @@ export class AppRail extends Component {
     header: null,
     footer: null,
     openDelay: 80,
-    closeDelay: 160
+    closeDelay: 160,
+    renderIcon: null
   };
 
   /**
    * Creates or enhances a rail host.
    * @param {Element|string|null} target Rail target.
-   * @param {AppRailOptions} [options={}] Rail options.
+   * @param {AppRailPresenterOptions} [options={}] Rail options.
    */
   constructor(target = null, options = {}) {
     super(target, options);
@@ -213,7 +215,14 @@ export class AppRail extends Component {
         index: String(item.id),
         iconOnly: true,
         disclosure: hasChildren,
-        disclosureIcon: railDisclosureIcon(this.el.dataset.side)
+        disclosureIcon: railDisclosureIcon(this.el.dataset.side),
+        visual: appNavIcon(item, this.options.renderIcon, {
+          orientation: this.el.dataset.orientation,
+          collapsed: true,
+          side: this.el.dataset.side,
+          level: 1,
+          location: 'root'
+        })
       });
       const row = h('li', { class: 'zx-app-rail__row' }, control);
       this.refs.list.append(row);
@@ -255,7 +264,14 @@ export class AppRail extends Component {
         index: childKey,
         iconOnly: false,
         disclosure: hasChildren,
-        disclosureIcon: nestedDisclosureIcon(this.el.dataset.side)
+        disclosureIcon: nestedDisclosureIcon(this.el.dataset.side),
+        visual: appNavIcon(child, this.options.renderIcon, {
+          orientation: this.el.dataset.orientation,
+          collapsed: true,
+          side: this.el.dataset.side,
+          level: childKey.split('/').length,
+          location: 'flyout'
+        })
       });
       list.append(h('li', {}, control));
       if (hasChildren) this._buildFlyout(child, control, childKey, key);
@@ -305,7 +321,6 @@ export class AppRail extends Component {
     this._interaction.listen(trigger, 'click', (event) => {
       event.preventDefault();
       if (event instanceof MouseEvent && event.detail === 0) this.openFlyout(key, { focus: true });
-      else if (dropdown.isOpen()) this.closeFlyout(key);
       else this.openFlyout(key);
     });
     this._interaction.listen(actualPanel, 'pointerenter', () => this._cancelFlyoutTimers(flyout, true));
@@ -582,26 +597,61 @@ class RailListenerScope extends Component {
 export function normalizeAppItems(items) {
   if (!Array.isArray(items)) return [];
   return items.filter((item) => item && typeof item === 'object' && item.id != null && item.label != null)
-    .map((item) => ({
-      ...item,
-      label: String(item.label),
-      children: Array.isArray(item.children) ? normalizeAppItems(item.children) : []
-    }));
+    .map((item) => {
+      const normalized = {
+        ...item,
+        label: String(item.label),
+        children: Array.isArray(item.children) ? normalizeAppItems(item.children) : []
+      };
+      if (item.href == null) return normalized;
+      const href = safeHref(item.href);
+      if (href !== null) normalized.href = href;
+      else {
+        delete normalized.href;
+        if (normalized.children.length === 0 && typeof normalized.invoke !== 'function') {
+          normalized.disabled = true;
+        }
+      }
+      return normalized;
+    });
+}
+
+/**
+ * Resolves a host-rendered or item-owned navigation icon without moving a mounted source node.
+ * @param {AppNavItem} item Navigation item.
+ * @param {unknown} renderer Optional component-level renderer.
+ * @param {Record<string, any>} context Presentation context.
+ * @returns {Node|null}
+ */
+export function appNavIcon(item, renderer, context) {
+  let visual = typeof renderer === 'function' ? renderer(item, context) : null;
+  if (visual == null) visual = item.icon;
+  if (typeof visual === 'function') visual = visual(context, item);
+  if (typeof visual === 'string') return icon(visual);
+  if (visual instanceof Node) return visual.cloneNode(true);
+  if (visual && typeof visual === 'object'
+    && typeof (/** @type {any} */ (visual)).toElement === 'function') {
+    const element = (/** @type {any} */ (visual)).toElement();
+    return element instanceof Node ? element.cloneNode(true) : null;
+  }
+  return null;
 }
 
-/** @param {AppNavItem} item @param {{className: string, index: string, iconOnly: boolean, disclosure: boolean, disclosureIcon: string}} options @returns {HTMLElement} */
-function navControl(item, { className, index, iconOnly, disclosure, disclosureIcon }) {
-  const tag = item.href && !disclosure ? 'a' : 'button';
+/** @param {AppNavItem} item @param {{className: string, index: string, iconOnly: boolean, disclosure: boolean, disclosureIcon: string, visual: Node|null}} options @returns {HTMLElement} */
+function navControl(item, { className, index, iconOnly, disclosure, disclosureIcon, visual }) {
+  const href = safeHref(item.href);
+  const tag = href && !disclosure ? 'a' : 'button';
   return /** @type {HTMLElement} */ (h(tag, {
     class: className,
     type: tag === 'button' ? 'button' : null,
-    href: tag === 'a' ? item.href : null,
+    href: tag === 'a' ? href : null,
     target: tag === 'a' ? item.target ?? null : null,
+    rel: tag === 'a' ? 'noopener' : null,
     ariaLabel: iconOnly ? item.label : null,
     ariaDisabled: item.disabled ? 'true' : null,
     dataset: { appNavId: index, appNavValueId: String(item.id) }
   },
-  item.icon ? h('span', { class: `${className}-icon`, ariaHidden: 'true' }, icon(item.icon)) : null,
+  visual ? h('span', { class: `${className}-icon`, ariaHidden: 'true' }, visual) : null,
   h('span', { class: `${className}-label` }, item.label),
   item.badge != null ? h('span', { class: `${className}-badge` }, String(item.badge)) : null,
   disclosure ? h('span', { class: `${className}-disclosure`, ariaHidden: 'true' }, icon(disclosureIcon)) : null));
@@ -664,5 +714,5 @@ function appendSlot(target, content) {
   } else if (typeof content === 'object' && typeof content.nodeType === 'number') target.append(content);
 }
 
-/** Fired when a destination/action is activated. @event AppRail#select @type {CustomEvent<AppNavSelectDetail>} */
-/** Fired when a flyout opens or closes. @event AppRail#flyoutchange @type {CustomEvent<{item: AppNavItem, id: string|number, open: boolean}>} */
+/** Fired when a destination/action is activated. @event AppRailPresenter#select @type {CustomEvent<AppNavSelectDetail>} */
+/** Fired when a flyout opens or closes. @event AppRailPresenter#flyoutchange @type {CustomEvent<{item: AppNavItem, id: string|number, open: boolean}>} */

package/src/zeyos/icons.js

@@ -55,6 +55,7 @@ export function moduleIcon(name, options = {}) {
  * @property {string|null} [label=null] Accessible label; null marks the chip decorative.
  * @property {boolean} [title=false] Adds the module's display name as a `title` tooltip.
  * @property {boolean} [standard=false] Use the stock Font Awesome fallback glyph.
+ * @property {string} [color] Override the module colour for a server-defined fork or weblet.
  * @property {string|string[]} [class] Extra class names.
  */
 
@@ -67,16 +68,20 @@ export function moduleIcon(name, options = {}) {
  * @returns {HTMLElement} A `<span class="zx-module-icon">` wrapping the glyph.
  */
 export function moduleChip(name, options = {}) {
-  const { size = 24, iconSize = '1em', label = null, title = false, standard = false } = options;
+  const {
+    size = 24, iconSize = '1em', label = null, title = false, standard = false,
+    color = null
+  } = options;
   const key = normalizeModuleName(name);
   const info = moduleInfo(name);
+  const background = color || info.color;
 
   const chip = h('span', {
     class: ['zx-module-icon', options.class].flat().filter(Boolean),
     dataset: { module: key },
     style: {
-      '--zx-module-color': info.color,
-      '--zx-module-glyph': moduleGlyphColor(info.color),
+      '--zx-module-color': background,
+      '--zx-module-glyph': moduleGlyphColor(background),
       '--zx-module-icon-size': typeof size === 'number' ? `${size}px` : String(size)
     },
     title: title ? info.label : null

package/src/zeyos/index.js

@@ -16,6 +16,12 @@ export {
   moduleGlyphColor, normalizeModuleName, registerModules
 } from './modules.js';
 export { ZEYOS_ICON_KIT, useZeyosIcons, moduleIcon, moduleChip } from './icons.js';
-export { zeyosSelect } from './select.js';
+export {
+  ZEYOS_LAUNCHER_APPLICATIONS, buildZeyosLauncherConfig, zeyosLauncher,
+  normalizeZeyosLauncherApplications, normalizeZeyosLauncherRecords, zeyosActiveIdentifier
+} from './launcher.js';
+export {
+  zeyosSelect, buildZeyosSelectConfig, zeyosEntitySelect, buildZeyosEntitySelectConfig
+} from './select.js';
 export { zeyosForm } from './form.js';
 export { zeyosTable } from './table.js';

package/src/zeyos/launcher.js

@@ -0,0 +1,338 @@
+import { Launcher } from '../components/launcher/launcher.js';
+import { moduleChip } from './icons.js';
+import { moduleInfo } from './modules.js';
+
+/** Static application identifiers present in the current ZeyOS shell prototype. */
+export const ZEYOS_LAUNCHER_APPLICATIONS = Object.freeze([
+  'accounts', 'actionsteps', 'admin', 'auth', 'billing', 'calendar', 'campaigns', 'collection',
+  'contacts', 'contracts', 'control', 'coupons', 'dev', 'documents', 'inventory', 'mailinglists',
+  'main', 'messages', 'links', 'notes', 'objects', 'opportunities', 'payments', 'pricelists',
+  'procurement', 'production', 'projects', 'tasks', 'tickets'
+]);
+
+/**
+ * @typedef {Object} ZeyosLauncherState
+ * @property {Record<string, string>|Array<string|Record<string, any>>} [modules={}] Permitted module catalogue.
+ * @property {Array<Array<any>|Record<string, any>>} [menuApps=[]] Forks/weblets and authoritative menu entries.
+ * @property {string[]} [pinned=[]] Application identifiers in pinned order.
+ * @property {Array<Array<any>|Record<string, any>>} [recent=[]] Recent records.
+ * @property {string|null} [activeIdentifier=null] Current module, `fork#…`, or `weblet#…` identifier.
+ * @property {(module: string) => boolean} [canUseModule] Permission predicate.
+ * @property {(query: string, context: {signal: AbortSignal}) => Promise<unknown>|unknown} [search] Record search loader.
+ * @property {(context: {signal: AbortSignal}) => Promise<unknown>|unknown} [loadRecent] Recent-record loader.
+ * @property {(app: unknown) => Record<string, any>|null} [resolveApplication] Maps an app to href/invoke/value metadata.
+ * @property {(record: unknown) => Record<string, any>|null} [resolveRecord] Maps a record to href/invoke/value metadata.
+ * @property {Record<string, any>} [labels] Localized applications/recent/results/entity labels and hints.
+ * @property {(app: unknown, normalized: Record<string, any>) => Node|null} [renderApplicationIcon] Host icon renderer for modules, forks, and weblets.
+ * @property {(record: unknown, normalized: Record<string, any>) => Node|null} [renderRecordIcon] Host record icon renderer.
+ * @property {(app: unknown, normalized: Record<string, any>) => Node|null} [renderWebletIcon] Legacy weblet-only icon renderer.
+ */
+
+/**
+ * @typedef {Object} ZeyosLauncherOptions
+ * @property {boolean} [standardIcons=false] Use stock icon fallbacks instead of the optional ZeyOS kit.
+ * @property {Array<Record<string, any>>} [items] Extra generic Launcher items.
+ * @property {Array<Record<string, any>>} [sources] Extra generic Launcher sources.
+ */
+
+/**
+ * Builds a generic Launcher configuration from explicitly injected ZeyOS shell state. It never
+ * reads PG/C globals and never resolves a route itself.
+ * @param {ZeyosLauncherState} [state={}] Application-owned shell state.
+ * @param {ZeyosLauncherOptions & Record<string, any>} [options={}] Adapter and Launcher options.
+ * @returns {Record<string, any>} Plain Launcher options.
+ */
+export function buildZeyosLauncherConfig(state = {}, options = {}) {
+  const {
+    standardIcons = false,
+    items: extraItems = [],
+    sources: extraSources = [],
+    ...launcherOptions
+  } = options;
+  const labels = launcherLabels(state.labels);
+  const iconOptions = {
+    standardIcons,
+    renderApplicationIcon: state.renderApplicationIcon,
+    renderWebletIcon: state.renderWebletIcon
+  };
+  const applications = normalizeZeyosLauncherApplications(state, iconOptions);
+  const recent = typeof state.loadRecent === 'function' ? []
+    : normalizeZeyosLauncherRecords(state.recent ?? [], {
+      query: '', labels, resolveRecord: state.resolveRecord,
+      renderRecordIcon: state.renderRecordIcon, standardIcons
+    });
+  const sources = [];
+  if (typeof state.loadRecent === 'function') {
+    sources.push({
+      id: 'zeyos-recent',
+      minQuery: 0,
+      when: 'empty',
+      order: 'source',
+      load: async (_query, context) => normalizeZeyosLauncherRecords(
+        await state.loadRecent(context),
+        {
+          query: '', labels, resolveRecord: state.resolveRecord,
+          renderRecordIcon: state.renderRecordIcon, standardIcons
+        }
+      )
+    });
+  }
+  if (typeof state.search === 'function') {
+    sources.push({
+      id: 'zeyos-records',
+      minQuery: 1,
+      when: 'query',
+      order: 'source',
+      load: async (query, context) => normalizeZeyosLauncherRecords(
+        await state.search(query, context),
+        {
+          query, labels, resolveRecord: state.resolveRecord,
+          renderRecordIcon: state.renderRecordIcon, standardIcons
+        }
+      )
+    });
+  }
+  sources.push(...extraSources);
+  return {
+    ...launcherOptions,
+    items: [...applications, ...recent, ...extraItems],
+    sources,
+    hints: options.hints ?? {
+      move: labels.move,
+      open: labels.open,
+      close: labels.close
+    }
+  };
+}
+
+/**
+ * Creates the ZeyOS-configured Launcher. State and route resolvers remain caller-owned inputs.
+ * @param {ZeyosLauncherState} [state={}] Injected shell state.
+ * @param {ZeyosLauncherOptions & Record<string, any>} [options={}] Adapter and Launcher options.
+ * @returns {Launcher}
+ */
+export function zeyosLauncher(state = {}, options = {}) {
+  return new Launcher(null, buildZeyosLauncherConfig(state, options));
+}
+
+/**
+ * Normalizes module, fork, and weblet applications while preserving menu authority and pin order.
+ * @param {ZeyosLauncherState} [state={}] Injected shell state.
+ * @param {{standardIcons?: boolean, renderApplicationIcon?: Function, renderWebletIcon?: Function}} [options={}] Icon options.
+ * @returns {Array<Record<string, any>>}
+ */
+export function normalizeZeyosLauncherApplications(state = {}, options = {}) {
+  const labels = launcherLabels(state.labels);
+  const pinned = Array.isArray(state.pinned) ? state.pinned.map(String) : [];
+  const seen = new Set();
+  const items = [];
+  const add = (raw, fallbackId = null, fallbackLabel = null) => {
+    const app = normalizeApplication(raw, fallbackId, fallbackLabel);
+    if (!app || seen.has(app.identifier)) return;
+    if (app.type === 'module' && typeof state.canUseModule === 'function'
+      && !state.canUseModule(app.module)) return;
+    seen.add(app.identifier);
+    const resolved = mergeDestination(app.raw, state.resolveApplication);
+    const pin = pinned.indexOf(app.identifier);
+    const icon = () => {
+      const custom = typeof options.renderApplicationIcon === 'function'
+        ? options.renderApplicationIcon(app.raw, app)
+        : app.type === 'weblet' && typeof options.renderWebletIcon === 'function'
+          ? options.renderWebletIcon(app.raw, app) : null;
+      return custom ?? moduleChip(app.module, {
+        size: 36,
+        standard: Boolean(options.standardIcons),
+        color: app.color
+      });
+    };
+    items.push({
+      id: app.identifier,
+      label: app.label,
+      keywords: [app.identifier, app.module],
+      group: labels.applications,
+      groupOrder: 0,
+      kind: 'application',
+      icon,
+      pinned: pin >= 0 ? pin : undefined,
+      current: app.identifier === state.activeIdentifier,
+      disabled: !resolved.href && typeof resolved.invoke !== 'function',
+      ...resolved,
+      _zeyos: app
+    });
+  };
+
+  for (const raw of Array.isArray(state.menuApps) ? state.menuApps : []) add(raw);
+  if (Array.isArray(state.modules)) {
+    for (const module of state.modules) {
+      if (typeof module === 'string') add([module, moduleInfo(module).label]);
+      else add(module, module?.id ?? module?.module, module?.label);
+    }
+  } else {
+    for (const [module, label] of Object.entries(state.modules ?? {})) add([module, label]);
+  }
+  return items;
+}
+
+/**
+ * Normalizes recent records or grouped search payloads without losing server/group order.
+ * @param {unknown} payload Recent/search payload.
+ * @param {{query?: string, labels?: Record<string, any>, resolveRecord?: Function, renderRecordIcon?: Function, standardIcons?: boolean}} [options={}] Mapping options.
+ * @returns {Array<Record<string, any>>}
+ */
+export function normalizeZeyosLauncherRecords(payload, options = {}) {
+  const query = String(options.query ?? '');
+  const labels = launcherLabels(options.labels);
+  const records = flattenRecords(payload, query);
+  const groupOrders = new Map();
+  return records.flatMap(({ raw, group }, itemOrder) => {
+    const record = normalizeRecord(raw, group, query);
+    if (!record) return [];
+    const groupName = query === '' ? labels.recent
+      : record.group === '' ? labels.results
+        : labels.entities[record.group] ?? record.group;
+    if (!groupOrders.has(groupName)) groupOrders.set(groupName, groupOrders.size + 1);
+    const resolved = mergeDestination(record.raw, options.resolveRecord);
+    return [{
+      id: `record:${record.entity}:${record.fork ?? ''}:${record.ID}`,
+      label: record.name,
+      description: record.sec,
+      keywords: [record.entity, record.ID, record.fork ?? ''],
+      group: groupName,
+      groupOrder: groupOrders.get(groupName),
+      itemOrder,
+      kind: 'record',
+      when: query === '' ? 'empty' : 'query',
+      icon: () => {
+        const custom = typeof options.renderRecordIcon === 'function'
+          ? options.renderRecordIcon(record.raw, record) : null;
+        return custom ?? moduleChip(record.entity, {
+          size: 28,
+          standard: Boolean(options.standardIcons)
+        });
+      },
+      disabled: !resolved.href && typeof resolved.invoke !== 'function',
+      ...resolved,
+      _zeyos: record
+    }];
+  });
+}
+
+/** @param {{module?: string, fork?: unknown, weblet?: unknown}} state @returns {string} */
+export function zeyosActiveIdentifier(state = {}) {
+  if (state.weblet != null && state.weblet !== '') return `weblet#${state.weblet}`;
+  if (state.fork != null && state.fork !== '') return `fork#${state.fork}`;
+  return String(state.module ?? '');
+}
+
+/** @param {unknown} raw @param {string|null} fallbackId @param {unknown} fallbackLabel @returns {Record<string, any>|null} */
+function normalizeApplication(raw, fallbackId, fallbackLabel) {
+  if (Array.isArray(raw)) {
+    if (raw.length < 2) return null;
+    if (raw.length === 2) {
+      const module = String(raw[0]);
+      return { raw, identifier: module, label: String(raw[1]), module, type: 'module', color: null };
+    }
+    if (raw.length === 4) {
+      const module = String(raw[2] || 'default');
+      return {
+        raw, identifier: `fork#${raw[0]}`, label: String(raw[1]), module, type: 'fork',
+        color: normalizeServerColor(raw[3])
+      };
+    }
+    return {
+      raw, identifier: `weblet#${raw[0]}`, label: String(raw[1]), module: 'weblets',
+      type: 'weblet', color: normalizeServerColor(raw[8])
+    };
+  }
+  if (!raw || typeof raw !== 'object') return null;
+  const identifier = String(raw.identifier ?? raw.id ?? fallbackId ?? '');
+  if (!identifier) return null;
+  const type = identifier.startsWith('fork#') ? 'fork'
+    : identifier.startsWith('weblet#') ? 'weblet' : 'module';
+  return {
+    raw,
+    identifier,
+    label: String(raw.label ?? fallbackLabel ?? moduleInfo(identifier).label),
+    module: String(raw.module ?? (type === 'module' ? identifier : type === 'fork' ? 'default' : 'weblets')),
+    type,
+    color: normalizeServerColor(raw.color)
+  };
+}
+
+/** @param {unknown} payload @param {string} query @returns {Array<{raw: unknown, group: string}>} */
+function flattenRecords(payload, query) {
+  if (Array.isArray(payload)) return payload.map((raw) => ({ raw, group: raw?.group ?? '' }));
+  if (!payload || typeof payload !== 'object') return [];
+  const result = [];
+  for (const [group, rows] of Object.entries(payload)) {
+    if (!Array.isArray(rows)) continue;
+    for (const row of rows) {
+      if (!Array.isArray(row)) {
+        result.push({ raw: row, group });
+        continue;
+      }
+      // Search payloads use [ID,fork,name,sec] under an entity key; top results carry entity last.
+      const raw = group === '' && row.length >= 5
+        ? { ID: row[0], fork: row[1], name: row[2], sec: row[3], entity: row[4], group }
+        : { ID: row[0], fork: row[1], name: row[2], sec: row[3], entity: group, group };
+      result.push({ raw, group });
+    }
+  }
+  return result;
+}
+
+/** @param {unknown} raw @param {string} group @param {string} query @returns {Record<string, any>|null} */
+function normalizeRecord(raw, group, query) {
+  if (Array.isArray(raw)) {
+    if (query === '' && raw.length >= 4) {
+      return {
+        raw, entity: String(raw[0]), ID: raw[1], fork: raw[2] ?? null,
+        name: String(raw[3]), sec: String(raw[4] ?? ''), group: ''
+      };
+    }
+    return null;
+  }
+  if (!raw || typeof raw !== 'object' || raw.ID == null || raw.name == null) return null;
+  return {
+    raw,
+    entity: String(raw.entity ?? group ?? 'records'),
+    ID: raw.ID,
+    fork: raw.fork ?? null,
+    name: String(raw.name),
+    sec: String(raw.sec ?? ''),
+    group: String(raw.group ?? group ?? '')
+  };
+}
+
+/** @param {unknown} raw @param {unknown} resolver @returns {Record<string, any>} */
+function mergeDestination(raw, resolver) {
+  const direct = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+  const resolved = typeof resolver === 'function' ? resolver(raw) : null;
+  const destination = resolved && typeof resolved === 'object' ? resolved : {};
+  return Object.fromEntries(['href', 'target', 'invoke', 'value'].flatMap((key) => {
+    const value = destination[key] ?? direct[key];
+    return value === undefined ? [] : [[key, value]];
+  }));
+}
+
+/** @param {unknown} value @returns {string|null} */
+function normalizeServerColor(value) {
+  const source = String(value ?? '').trim();
+  if (!source) return null;
+  const color = source.startsWith('#') ? source : `#${source}`;
+  return /^#[\da-f]{3}(?:[\da-f]{3})?$/i.test(color) ? color : null;
+}
+
+/** @param {unknown} input @returns {Record<string, any>} */
+function launcherLabels(input) {
+  const labels = input && typeof input === 'object' ? input : {};
+  return {
+    applications: String(labels.applications ?? 'Applications'),
+    recent: String(labels.recent ?? 'Recent'),
+    results: String(labels.results ?? 'Top results'),
+    entities: labels.entities && typeof labels.entities === 'object' ? labels.entities : {},
+    move: String(labels.move ?? 'Move'),
+    open: String(labels.open ?? 'Open'),
+    close: String(labels.close ?? 'Close')
+  };
+}

package/src/zeyos/modules.js

@@ -109,6 +109,7 @@ export const zeyosModules = Object.freeze({
  * @type {Readonly<Record<string, string>>}
  */
 export const moduleAliases = Object.freeze({
+  main: 'zeyos',
   addresses: 'contacts',
   clocking: 'actionsteps',
   comments: 'notes',