bmweb-cli 0.1.0

package/runtime/screens/ipo-runtime/protocol.js

@@ -0,0 +1,464 @@
+/**
+ * @file The whole-vehicle protocol as data. A script's "read every module"
+ * key puts FS_LESEN on the wire per group and writes a text file; the
+ * runtime also kept every answer. This joins those answers with the app's
+ * fault dictionaries (names, P-codes, the lookup), draws them the way the
+ * module error scan draws its result, and prints them like its report.
+ * INPA's own text stays one toggle away, and is what F9 prints below the
+ * table.
+ */
+
+/** the fault-memory reads a whole-vehicle script sends per module */
+const IPO_FAULT_READ_RE = /^(FS|IS)_LESEN$/;
+/** the per-fault detail read the same script sends afterwards */
+const IPO_FAULT_DETAIL_RE = /^(FS|IS)_LESEN_DETAIL$/;
+/** the identification read the same script sends per module (F2 Ident) */
+const IPO_IDENT_READ_RE = /^IDENT$/;
+/** the module info read that precedes it (REVISION, ECU) */
+const IPO_INFO_READ_RE = /^INFO$/;
+/**
+ * The identification fields the script prints, in its order, with the
+ * caption each row gets. A pair of keys is one row (week / year).
+ * @type {Array<[string[], string]>}
+ */
+const IPO_IDENT_ROWS = [
+  [['VARIANTE'], 'Variant'],
+  [['REVISION'], 'Version'],
+  [['ID_BMW_NR'], 'BMW part number'],
+  [['ID_HW_NR'], 'Hardware number'],
+  [['ID_SW_NR'], 'Software number'],
+  [['ID_LIEF_TEXT'], 'Supplier'],
+  [['ID_LIEF_NR'], 'Supplier number'],
+  [['ID_COD_INDEX'], 'Coding index'],
+  [['ID_VAR_INDEX'], 'Variant index'],
+  [['ID_DIAG_INDEX'], 'Diagnosis index'],
+  [['ID_BUS_INDEX'], 'Bus index'],
+  [['ID_DATUM_KW', 'ID_DATUM_JAHR'], 'Build date (week/year)'],
+  [['FG_NR'], 'Chassis number'],
+  [['COD_AE_INDEX'], 'Coding data change index'],
+];
+/** the protocol's overview line: "MRS4 2    Airbag ..." / "D_009C *    Cabrio ..." */
+const IPO_PROTOCOL_OVERVIEW_RE = /^(\S+)\s+(\d+|\*)\s+(\S.*)$/;
+
+/**
+ * @typedef {object} IpoWireRead
+ * @property {string} target - the SGBD the script named (a group, or a variant)
+ * @property {string} [variant] - the SGBD that answered (VARIANTE)
+ * @property {string} job
+ * @property {string|null} [arg]
+ * @property {object[]} [sets] - the job's data sets
+ * @property {string} [error] - the failure, when nothing answered
+ */
+
+/**
+ * @typedef {object} IpoProtocolModule
+ * @property {string} sgbd - the variant that answered, lower-case
+ * @property {string} via - the group it was reached through
+ * @property {string} label - the module's name (the script's, or the app's)
+ * @property {object[]} codes - FS_LESEN entries, detail merged in
+ * @property {object} [ident] - the IDENT answer (and INFO's REVISION) for an ident read
+ */
+
+/**
+ * @typedef {object} IpoProtocolReport
+ * @property {'faults'|'ident'} kind - what the read was: fault memories, or identifications
+ * @property {IpoProtocolModule[]} modules - every module that answered, script order
+ * @property {{target: string, label: string, error: string}[]} silent - addresses that did not
+ * @property {boolean} showText - the viewer is on INPA's text, not the table
+ */
+
+/**
+ * Fold what the read put on the wire into one record per module.
+ * @param {IpoWireRead[]} reads - the body's wire log
+ * @param {string[]} [lines] - the protocol's text (its overview names the modules)
+ * @returns {IpoProtocolReport}
+ */
+function ipoProtocolReport(reads, lines) {
+  const names = ipoProtocolNames(lines);
+  const modules = new Map();
+  const silent = new Map();
+  let kind = 'faults';
+  const first = (sets) => (sets || []).find((s) => Object.keys(s).length) || {};
+  /** INFO answers by module: the script asks INFO before IDENT */
+  const revisions = new Map();
+  for (const r of reads || []) {
+    const job = String(r.job || '').toUpperCase();
+    if (r.error) {
+      if (
+        (IPO_FAULT_READ_RE.test(job) || IPO_IDENT_READ_RE.test(job)) &&
+        !silent.has(r.target)
+      )
+        silent.set(r.target, r.error);
+      continue;
+    }
+    const sgbd = String(r.variant || r.target).toLowerCase();
+    if (IPO_IDENT_READ_RE.test(job)) {
+      // F2 Ident: one IDENT per group, its answer is the module's record
+      kind = 'ident';
+      silent.delete(r.target);
+      if (!modules.has(sgbd)) {
+        modules.set(sgbd, {
+          sgbd,
+          via: String(r.target).toLowerCase(),
+          label:
+            names.get(sgbd) ||
+            names.get(String(r.target).toLowerCase()) ||
+            sgbd,
+          codes: [],
+          ident: { REVISION: revisions.get(sgbd), ...first(r.sets) },
+        });
+      }
+    } else if (IPO_INFO_READ_RE.test(job)) {
+      // INFO runs first: its REVISION is the version the script prints
+      const rev = first(r.sets).REVISION;
+      if (rev != null) revisions.set(sgbd, rev);
+      const m = modules.get(sgbd);
+      if (m && m.ident && rev != null && m.ident.REVISION == null)
+        m.ident.REVISION = rev;
+    } else if (IPO_FAULT_READ_RE.test(job)) {
+      silent.delete(r.target);
+      const codes = (r.sets || []).filter((c) => c.F_HEX_CODE || c.F_ORT_NR);
+      const m = modules.get(sgbd);
+      if (!m) {
+        modules.set(sgbd, {
+          sgbd,
+          via: String(r.target).toLowerCase(),
+          label:
+            names.get(sgbd) ||
+            names.get(String(r.target).toLowerCase()) ||
+            sgbd,
+          codes,
+        });
+      } else if (codes.length && !m.codes.length) {
+        m.codes = codes;
+      }
+    } else if (IPO_FAULT_DETAIL_RE.test(job)) {
+      const m = modules.get(sgbd);
+      if (!m) continue;
+      const nr = ipoProtocolFaultNr(r.arg);
+      const code = m.codes.find((c) => Number(c.F_ORT_NR) === nr);
+      const det = code ? ipoProtocolMatchDetail(r.sets, nr) : null;
+      if (det) {
+        // the detail's own hex/text never replace the memory's (wire.js
+        // keeps them the same way)
+        const { F_HEX_CODE, F_ORT_TEXT, ...rich } = det;
+        Object.assign(code, rich);
+      }
+    }
+  }
+  // a group the script asked again by its variant name is one module
+  return {
+    kind,
+    modules: [...modules.values()],
+    silent: [...silent.entries()].map(([target, error]) => ({
+      target,
+      label: names.get(target) || target.toUpperCase(),
+      error,
+    })),
+    showText: false,
+  };
+}
+
+/**
+ * The detail set for one fault: the set that names the number, else -- when
+ * no set names any number -- the one carrying a P-code or hex (the same
+ * rule the module error scan applies, sweep/wire.js matchDetail).
+ * @param {object[]} sets - the detail job's data sets
+ * @param {number} nr - the fault number asked about
+ * @returns {object|null}
+ */
+function ipoProtocolMatchDetail(sets, nr) {
+  const list = sets || [];
+  const named = list.find((s) => Number(s.F_ORT_NR) === nr);
+  if (named) return named;
+  if (list.some((s) => s.F_ORT_NR != null)) return null;
+  return list.find((s) => s.F_PCODE_STRING || s.F_HEX_CODE) || null;
+}
+
+/**
+ * The fault number a detail read was asked about ("0x1F", "31").
+ * @param {string|null|undefined} arg
+ * @returns {number}
+ */
+function ipoProtocolFaultNr(arg) {
+  const s = String(arg == null ? '' : arg).trim();
+  return /^0x/i.test(s) ? parseInt(s.slice(2), 16) : parseInt(s, 10);
+}
+
+/**
+ * Module names from the protocol's overview table, keyed by the SGBD or
+ * group name in lower case.
+ * @param {string[]} [lines]
+ * @returns {Map<string, string>}
+ */
+function ipoProtocolNames(lines) {
+  const names = new Map();
+  for (const l of lines || []) {
+    const m = IPO_PROTOCOL_OVERVIEW_RE.exec(String(l).trim());
+    if (m && /^[A-Za-z0-9_]+$/.test(m[1]))
+      names.set(m[1].toLowerCase(), m[3].trim());
+  }
+  return names;
+}
+
+/**
+ * Draw the report into the module view: the scan's rows (one per module,
+ * fault detail rows under those with faults, "no response" for the silent
+ * ones) with a toggle to INPA's own text.
+ * @param {HTMLElement} el - the screen area
+ * @param {object} p - the running program (its view carries the report)
+ * @returns {Promise<void>}
+ */
+async function ipoProtocolRender(el, p) {
+  const view = p.view;
+  const rep = view && view.report;
+  if (!rep) return;
+  const withFaults = rep.modules.filter((m) => m.codes.length);
+  const total = withFaults.reduce((n, m) => n + m.codes.length, 0);
+  const head =
+    rep.kind === 'ident'
+      ? `${rep.modules.length} module${rep.modules.length === 1 ? '' : 's'} answered · ` +
+        `${rep.silent.length} no response`
+      : `${withFaults.length} module${withFaults.length === 1 ? '' : 's'} with faults · ` +
+        `${total} fault${total === 1 ? '' : 's'} · ` +
+        `${rep.modules.length} read · ${rep.silent.length} no response`;
+  // the bar (counts + the toggle) stays whichever side is showing
+  el.innerHTML =
+    `<div class="quick-sweep ipo-protocol-report">` +
+    `<div class="quick-bar"><div class="quick-head">${esc(head)}</div>` +
+    `<div class="quick-bar-btns"><button class="btn ipo-protocol-toggle"></button></div></div>` +
+    `<div class="quick-rows"></div>` +
+    `<pre class="ipo-protocol mono" hidden></pre></div>`;
+  const rowsEl = el.querySelector('.quick-rows');
+  const pre = el.querySelector('.ipo-protocol');
+  const toggle = el.querySelector('.ipo-protocol-toggle');
+  pre.textContent = (view.lines || []).join('\n');
+  const side = () => {
+    rowsEl.hidden = !!rep.showText;
+    pre.hidden = !rep.showText;
+    toggle.textContent = rep.showText ? 'Report' : 'INPA text';
+  };
+  toggle.onclick = () => {
+    rep.showText = !rep.showText;
+    side();
+  };
+  side();
+  if (typeof loadFaultDb === 'function') await loadFaultDb();
+  if (p.view !== view) return; // the script moved on while the DB loaded
+  for (const m of rep.modules) {
+    const row = addSweepRow(rowsEl, ipoText(m.label || m.sgbd));
+    if (rep.kind === 'ident') {
+      // identification: the module answered; its record under it
+      row.classList.add('clean');
+      row.querySelector('.quick-status').textContent = m.sgbd;
+      ipoProtocolIdentRows(row, m);
+      ipoProtocolBetterLabel(m, row, null);
+      continue;
+    }
+    if (!m.codes.length) {
+      row.classList.add('clean');
+      row.querySelector('.quick-status').textContent = 'OK';
+    } else {
+      // the scan's row: the count and a Clear that runs FS_LOESCHEN on the
+      // module and re-reads it (sweep/rows.js clearModule)
+      row.classList.add('has-faults');
+      const f = { row, codes: m.codes, ecu: { sgbd: m.sgbd, label: m.label } };
+      setRowFaultStatus(f);
+      appendFaultDetailRows(row, m.codes, m.sgbd);
+      ipoProtocolLinkLookup(row.nextElementSibling, m);
+      ipoProtocolBetterLabel(m, row, f);
+      continue;
+    }
+    ipoProtocolBetterLabel(m, row, null);
+  }
+  for (const s of rep.silent) {
+    const row = addSweepRow(rowsEl, ipoText(s.label));
+    setRowNoResponse(row, 'no response');
+  }
+}
+
+/**
+ * The identification record under a module's row: the fields the script
+ * prints, in its order, only those the module answered.
+ * @param {HTMLElement} row - the module's row
+ * @param {IpoProtocolModule} m
+ * @returns {void}
+ */
+function ipoProtocolIdentRows(row, m) {
+  const id = m.ident || {};
+  const val = (keys) =>
+    keys
+      .map((k) => (id[k] == null ? '' : String(id[k]).trim()))
+      .filter((v) => v && !v.startsWith('_'))
+      .join(' / ');
+  const items = IPO_IDENT_ROWS.map(([keys, cap]) => [cap, val(keys)]).filter(
+    ([, v]) => v
+  );
+  if (!items.length) return;
+  const wrap = document.createElement('div');
+  wrap.className = 'quick-detail';
+  wrap.innerHTML = items
+    .map(
+      ([cap, v]) =>
+        `<div class="quick-detail-row"><span class="quick-detail-code">${esc(cap)}</span>` +
+        `<span class="quick-detail-name mono">${esc(v)}</span></div>`
+    )
+    .join('');
+  row.insertAdjacentElement('afterend', wrap);
+}
+
+/**
+ * The app's own name for the variant (the chassis config's), once it is
+ * known: the script's German label is what the row shows until then.
+ * @param {IpoProtocolModule} m
+ * @param {HTMLElement} row
+ * @param {object|null} f - the row's clear record, whose label follows
+ * @returns {void}
+ */
+function ipoProtocolBetterLabel(m, row, f) {
+  if (typeof variantLabel !== 'function') return;
+  variantLabel(m.sgbd)
+    .then((name) => {
+      if (name && row.isConnected) {
+        m.label = name;
+        if (f) f.ecu.label = name;
+        setRowLabel(row, name, `${m.sgbd} via ${m.via}`);
+      }
+    })
+    .catch(() => {});
+}
+
+/**
+ * Each fault detail row opens the Fault Lookup on that code.
+ * @param {HTMLElement|null} detailEl - the rows appendFaultDetailRows added
+ * @param {IpoProtocolModule} m
+ * @returns {void}
+ */
+function ipoProtocolLinkLookup(detailEl, m) {
+  if (!detailEl || typeof setDtcParam !== 'function') return;
+  const rows = detailEl.querySelectorAll('.quick-detail-row');
+  rows.forEach((row, i) => {
+    const c = m.codes[i];
+    if (!c) return;
+    const ff = faultFields(c, m.sgbd);
+    row.classList.add('ipo-protocol-link');
+    row.title = 'Open in Fault Lookup';
+    row.onclick = () => {
+      setDtcParam(hexText(c.F_HEX_CODE) || ff.code, m.sgbd, ff.name);
+      if (typeof showLookup === 'function') showLookup();
+    };
+  });
+}
+
+/**
+ * The printed sheet's sections for a protocol: the scan report's tables per
+ * module with faults, the silent addresses, then INPA's own text.
+ * @param {object} view - the program's view ({lines, report})
+ * @returns {object[]} print sections (core/print.js)
+ */
+function ipoProtocolPrintSections(view) {
+  const rep = view.report;
+  const sections = [];
+  const text = {
+    html: `<pre class="pr-screen">${esc((view.lines || []).join('\n'))}</pre>`,
+  };
+  if (rep.kind === 'ident') return ipoProtocolIdentPrint(rep, text);
+  // the scan report's table helpers (sweep/report.js) draw the tables; a
+  // page without them still prints INPA's text
+  if (
+    typeof faultColumns !== 'function' ||
+    typeof printFaultTable !== 'function'
+  )
+    return [text];
+  const withFaults = rep.modules.filter((m) => m.codes.length);
+  const columns = faultColumns();
+  if (!withFaults.length) {
+    sections.push(
+      printHtml(
+        `<p class="pr-p">No stored faults. ${rep.modules.length} module` +
+          `${rep.modules.length === 1 ? '' : 's'} read, ${rep.silent.length} did not answer.</p>`
+      )
+    );
+  }
+  for (const m of withFaults) {
+    sections.push(
+      printHeading(
+        `${ipoText(m.label)}  ·  ${m.sgbd}  ·  ` +
+          `${m.codes.length} fault${m.codes.length === 1 ? '' : 's'}`
+      )
+    );
+    sections.push({
+      html: printFaultTable(
+        { ecu: { sgbd: m.sgbd, label: ipoText(m.label) }, codes: m.codes },
+        columns
+      ),
+    });
+  }
+  if (rep.silent.length) {
+    sections.push(
+      printHtml(
+        `<p class="pr-p">No response: ${esc(
+          rep.silent.map((s) => ipoText(s.label)).join(', ')
+        )}</p>`
+      )
+    );
+  }
+  sections.push(printHeading("INPA's protocol"));
+  sections.push(text);
+  return sections;
+}
+
+/**
+ * The printed sheet for an identification read: one table of the modules
+ * that answered (part, hardware and software numbers, build week), the
+ * silent addresses, then INPA's text.
+ * @param {IpoProtocolReport} rep
+ * @param {object} text - the section with INPA's text
+ * @returns {object[]} print sections (core/print.js)
+ */
+function ipoProtocolIdentPrint(rep, text) {
+  if (typeof printTable !== 'function') return [text];
+  const sections = [];
+  const t = printTable(
+    ['Module', 'SGBD', 'Part no.', 'HW', 'SW', 'Build wk/yr'],
+    rep.modules.map((m) => {
+      const id = m.ident || {};
+      const v = (k) => (id[k] == null ? '—' : String(id[k]));
+      return [
+        ipoText(m.label),
+        m.sgbd,
+        v('ID_BMW_NR'),
+        v('ID_HW_NR'),
+        v('ID_SW_NR'),
+        `${v('ID_DATUM_KW')}/${v('ID_DATUM_JAHR')}`,
+      ];
+    }),
+    ['', 'pr-code2', 'pr-code2', '', '', '']
+  );
+  t.avoidBreak = false;
+  sections.push(
+    printHeading(
+      `${rep.modules.length} module${rep.modules.length === 1 ? '' : 's'} answered`
+    ),
+    t
+  );
+  if (rep.silent.length)
+    sections.push(
+      printHtml(
+        `<p class="pr-p">No response: ${esc(
+          rep.silent.map((s) => ipoText(s.label)).join(', ')
+        )}</p>`
+      )
+    );
+  sections.push(printHeading("INPA's protocol"), text);
+  return sections;
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = {
+    ipoProtocolReport,
+    ipoProtocolNames,
+    ipoProtocolFaultNr,
+    ipoProtocolPrintSections,
+  };
+}

package/runtime/screens/ipo-runtime/script-scan.js

@@ -0,0 +1,225 @@
+/**
+ * @file Static scans over a decoded script (the exec's procs), used by the
+ * runtime without executing anything: a menu's ITEM keys and prologue, the
+ * backdrop screen a menu is normally shown with, and a screen's component
+ * and logical-line declarations.
+ *
+ * Live .IPO runtime: the module view IS the running script. The derived IR
+ * (data/inpa-ir) approximated what a script would do and was corrected by
+ * heuristics; each heuristic was a place the guess differed from a run. This
+ * runtime runs the script instead: `inpainit` names the root menu and
+ * screen, a menu's ITEMs are the keys, a key press runs its body in the SAME
+ * VM the previous press left behind, a screen's LINE blocks paint cells and
+ * send their own jobs (keep-alives included), and a frequent screen re-runs
+ * its cycle on a timer -- INPA's own INIT -> LINE -> EXIT tick. Nothing
+ * above the VM decides what a key does.
+ */
+
+/** F-key numbers above this are the shifted bank (Shift+F1 = 11). */
+const IPO_SHIFT_BASE = 10;
+
+/**
+ * One key of a menu: an ITEM token and where its body lies in the proc.
+ * @typedef {object} IpoMenuItem
+ * @property {number} nr - F-key number (11..20 = shifted)
+ * @property {string} label - the caption as the script wrote it
+ * @property {boolean} shift - a Shift+F key
+ * @property {boolean} hidden - no caption: INPA's bar shows it blank
+ * @property {number} start - first token index of the body
+ * @property {number} end - token index the body ends at (exclusive)
+ * @property {string} [legendLabel] - the caption the screen's legend gave a hidden key
+ */
+
+/**
+ * ITEM tokens of a menu proc, in proc order.
+ * @param {object} exec - the decoded script ({procs, byid})
+ * @param {string} menuName - the menu proc
+ * @returns {IpoMenuItem[]}
+ */
+function ipoMenuItems(exec, menuName) {
+  const toks = exec && exec.procs && exec.procs[menuName];
+  if (!Array.isArray(toks)) return [];
+  const out = [];
+  for (let i = 0; i < toks.length; i++) {
+    const t = toks[i];
+    if (t.op !== 'ITEM') continue;
+    let end = toks.length;
+    for (let j = i + 1; j < toks.length; j++) {
+      if (toks[j].op === 'ITEM' || toks[j].op === 'unk') {
+        end = j;
+        break;
+      }
+    }
+    out.push({
+      nr: t.nr,
+      label: t.label || '',
+      shift: t.nr > IPO_SHIFT_BASE,
+      hidden: !String(t.label || '').trim(),
+      start: i + 1,
+      end,
+    });
+  }
+  return out;
+}
+
+/**
+ * Where a menu proc's prologue ends (the first ITEM), or the proc end.
+ * @param {object} exec - the decoded script
+ * @param {string} menuName - the menu proc
+ * @returns {number} token index
+ */
+function ipoPrologueEnd(exec, menuName) {
+  const toks = exec && exec.procs && exec.procs[menuName];
+  if (!Array.isArray(toks)) return 0;
+  const i = toks.findIndex((t) => t.op === 'ITEM');
+  return i < 0 ? toks.length : i;
+}
+
+/**
+ * The setscreen call in an ITEM body, walking back from a token: the screen
+ * ref and the frequent flag pushed before the call.
+ * @param {IpoToken[]} toks - the proc's tokens
+ * @param {number} j - index of the setscreen call
+ * @param {Record<string, string>} byid - the exec's byid table
+ * @returns {{screen: string, frequent: boolean}|null}
+ */
+function ipoSetscreenArgs(toks, j, byid) {
+  let ref = null,
+    flag = false;
+  for (let k = j - 1; k >= 0 && toks[k].op !== 'frame'; k--) {
+    if (toks[k].op === 'procref' && toks[k].kind === IPO_REF_SCREEN)
+      ref = toks[k];
+    if (toks[k].op === 'const' && (toks[k].t === 'b' || toks[k].t === 'i'))
+      flag = !!toks[k].v;
+  }
+  const scr = ref && byid[`screen:${ref.n}`];
+  return scr ? { screen: scr, frequent: flag } : null;
+}
+
+/**
+ * The menu whose prologue shows a screen: the inverse of ipoScreenForMenu,
+ * for a link that names a screen but no menu (a search result for the
+ * screen itself). The screen's keys are the owning menu's, so landing on the
+ * screen under any other menu puts the wrong jobs on the F-keys.
+ * @param {object} exec - the decoded script
+ * @param {string} screen - the screen proc name
+ * @returns {string|null} the menu name, or null when no menu shows it
+ */
+function ipoMenuForScreen(exec, screen) {
+  const byid = (exec && exec.byid) || {};
+  for (const [k, name] of Object.entries(byid)) {
+    if (!k.startsWith('menu:')) continue;
+    const shown = ipoScreenForMenu(exec, name); // {screen, frequent} or null
+    if (shown && shown.screen === screen) return name;
+  }
+  return null;
+}
+
+/**
+ * The backdrop a menu is normally shown with: the setscreen the key that
+ * opens it performs right before its setmenu. A deep link (the URL route)
+ * lands on the menu without pressing that key, so its screen is looked up
+ * here rather than left as whatever was current.
+ * @param {object} exec - the decoded script
+ * @param {string} menuName - the menu proc
+ * @returns {{screen: string, frequent: boolean}|null}
+ */
+function ipoScreenForMenu(exec, menuName) {
+  const byid = (exec && exec.byid) || {};
+  const menuId = Object.entries(byid).find(
+    ([k, v]) => k.startsWith('menu:') && v === menuName
+  );
+  if (!menuId) return null;
+  const mid = Number(menuId[0].split(':')[1]);
+  for (const toks of Object.values(exec.procs || {})) {
+    for (let i = 0; i < toks.length; i++) {
+      const t = toks[i];
+      if (!(t.op === 'procref' && t.kind === IPO_REF_MENU && t.n === mid))
+        continue;
+      const nxt = toks[i + 1];
+      if (!(nxt && nxt.op === 'call' && nxt.name === 'setmenu')) continue;
+      // walk back within the same ITEM body for a setscreen
+      for (let j = i - 1; j >= 0 && toks[j].op !== 'ITEM'; j--) {
+        const c = toks[j];
+        if (c.op === 'call' && c.name === 'setscreen') {
+          const found = ipoSetscreenArgs(toks, j, byid);
+          if (found) return found;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * The LINE declarations of a screen that carry a component key: INPA's
+ * togglelist offers exactly these.
+ * @param {object} exec - the decoded script
+ * @param {string|null} screen - the screen proc
+ * @returns {Array<{label: string, keys: string}>}
+ */
+function ipoScreenComponents(exec, screen) {
+  const toks = exec && exec.procs && screen ? exec.procs[screen] : null;
+  if (!toks) return [];
+  return toks
+    .filter((t) => t.op === 'LINE' && t.keys)
+    .map((t) => ({ label: t.label || '', keys: String(t.keys) }));
+}
+
+/**
+ * The named logical lines of a screen: what INPA's Select offers.
+ * @param {object} exec - the decoded script
+ * @param {string|null} screen - the screen proc
+ * @returns {string[]}
+ */
+function ipoScreenLineNames(exec, screen) {
+  const toks = exec && exec.procs && screen ? exec.procs[screen] : null;
+  if (!toks) return [];
+  const out = [];
+  for (const t of toks) {
+    if (t.op === 'LINE' && t.label && String(t.label).trim())
+      if (!out.includes(t.label)) out.push(t.label);
+  }
+  return out;
+}
+
+/**
+ * The keys of a menu whose body sets a screen that has named lines: what
+ * Select can filter once that key is pressed. Shown in the Select box when
+ * the current screen has nothing to choose from.
+ * @param {object} exec - the decoded script
+ * @param {string} menuName - the menu proc
+ * @param {IpoMenuItem[]} items - the menu's keys (ipoMenuItems)
+ * @returns {Array<{nr: number, shift: boolean, screen: string, lines: number}>}
+ */
+function ipoSelectableKeys(exec, menuName, items) {
+  const toks = exec && exec.procs && exec.procs[menuName];
+  if (!Array.isArray(toks)) return [];
+  const byid = exec.byid || {};
+  const out = [];
+  for (const it of items || []) {
+    let screen = null;
+    for (let j = it.start; j < it.end; j++) {
+      if (toks[j].op === 'call' && toks[j].name === 'setscreen') {
+        const a = ipoSetscreenArgs(toks, j, byid);
+        if (a) screen = a.screen;
+      }
+    }
+    if (!screen) continue;
+    const lines = ipoScreenLineNames(exec, screen).length;
+    if (lines) out.push({ nr: it.nr, shift: !!it.shift, screen, lines });
+  }
+  return out;
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = {
+    IPO_SHIFT_BASE,
+    ipoSelectableKeys,
+    ipoMenuItems,
+    ipoPrologueEnd,
+    ipoScreenForMenu,
+    ipoScreenComponents,
+    ipoScreenLineNames,
+  };
+}