@tablefolk/menus 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @tablefolk/menus
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+JRPG-style menus for games and apps. The player clicks a choice, presses its
+number, uses the arrows and Enter, or types or says what they want.
+
+Words are matched to a choice cheapest first:
+
+1. a number ("2", "the second one", "the last");
+2. the label or a keyword;
+3. shared words;
+4. meaning, through an embedding model you give it;
+5. a language model you give it, picking a number.
+
+Any step can answer "none of these".
+
+```js
+import { match, modelChooser, createMenuBox } from '@tablefolk/menus';
+const menu = { title: 'Brakka', text: 'What do you need?', other: true,
+  items: [{ id: 'buy', label: 'Buy a sword' }, { id: 'fix', label: 'Repair my armour', keywords: ['mend'] }, { id: 'bye', label: 'Leave' }] };
+
+await match(menu, 'can you mend it')     // { item: {id:'fix',...}, by: 'keyword', score: 1 }
+// close between a few choices by meaning, with no model to decide: { none: true, by: 'unsure', unsure: [items] }
+// (the box then asks "did you mean 1. ... or 2. ...?")
+
+const box = createMenuBox({
+  matchOptions: () => ({ choose: modelChooser((messages, o) => brain.chat(messages, o)) }),   // optional
+  onChoose: (item, { how, text }) => console.log(item.id, how),
+  onOther: text => console.log('none fit:', text),
+});
+await box.open(menu);          // { item, how, text } | { other: true, text } | null
+box.offer(speechText);         // words from your own text field or speech input
+```
+
+It needs no models of its own. Give it `embed(query, texts)` (similarities)
+and `choose` (any chat model: `modelChooser`, or `@tablefolk/brain`'s
+`pick`). The box brings a default look (`.menu-box`); `styles: false` leaves
+the look to you.
+
+Part of [Tablefolk](https://github.com/runvnc/tablefolk) (`libs/`). MIT.

package/box.js

@@ -0,0 +1,128 @@
+// The menu box on screen: click a choice, press 1-9, arrows and Enter, Esc
+// closes; words (typed into your own field, or from speech) go to offer().
+//
+//   import { createMenuBox } from '@tablefolk/menus';
+//   const box = createMenuBox({
+//     matchOptions: () => ({ embed, choose }),   // what match() may use (see index.js)
+//     onChoose: (item, { menu, how, text }) => {},
+//     onOther: (text, menu) => {},               // words that fit none, when menu.other
+//   });
+//   const r = await box.open(menu);   // { item, how, text } | { other: true, text } | null (closed)
+//   box.offer('the second one')       // true when the open menu took the words
+//   box.close(); box.active           // the open menu or null
+// Styles: a default look is added to the page once (injectMenuStyles; pass
+// styles: false to style .menu-box yourself).
+import { match, normalizeMenu } from './index.js';
+
+const esc = s => String(s ?? '').replace(/[&<>"]/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+
+export const MENU_CSS = `
+.menu-box { position:fixed; left:50%; bottom:92px; transform:translateX(-50%); z-index:60; width:min(440px, calc(100vw - 32px));
+  background:linear-gradient(180deg, rgba(22,26,44,.97), rgba(12,14,26,.97)); border:2px solid #d9c27a; border-radius:12px;
+  box-shadow:0 0 0 3px rgba(0,0,0,.55), 0 14px 40px rgba(0,0,0,.6); color:#f3ecd6; padding:10px 12px 8px; font-size:15px; box-sizing:border-box; }
+.menu-box[hidden] { display:none; }
+.menu-head { display:flex; align-items:center; justify-content:space-between; gap:8px; }
+.menu-head b { flex:1; color:#f2d27c; font-size:15px; letter-spacing:.02em; }
+.menu-x { flex:0 0 auto; width:auto; background:none; border:0; color:#cbbf9a; font-size:15px; cursor:pointer; padding:2px 6px; }
+.menu-text { margin:6px 0 4px; line-height:1.35; }
+.menu-items { list-style:none; margin:6px 0 4px; padding:0; display:flex; flex-direction:column; gap:3px; max-height:46vh; overflow:auto; }
+.menu-items button { display:flex; align-items:center; gap:10px; width:100%; text-align:left; background:transparent; border:1px solid transparent; border-radius:8px;
+  color:inherit; font:inherit; padding:7px 10px 7px 26px; cursor:pointer; position:relative; }
+.menu-items button.sel { background:rgba(217,194,122,.14); border-color:rgba(217,194,122,.45); }
+.menu-items button.sel::before { content:"▶"; position:absolute; left:8px; color:#f2d27c; font-size:11px; }
+.menu-num { min-width:18px; color:#9fb3d9; font-size:12px; font-variant-numeric:tabular-nums; }
+.menu-hint { font-size:11.5px; color:#a8a08a; margin-top:4px; }
+@media (max-width: 600px) { .menu-box { bottom:76px; font-size:14px; } .menu-items button { padding:9px 10px 9px 26px; } }
+`;
+export function injectMenuStyles(doc = document) {
+  if (doc.getElementById('tf-menu-styles')) return;
+  const s = doc.createElement('style'); s.id = 'tf-menu-styles'; s.textContent = MENU_CSS;
+  doc.head.prepend(s);   // first, so the page's own rules win
+}
+
+export function createMenuBox({ parent = null, id = 'menuBox', matchOptions = () => ({}), onChoose = null, onOther = null, onOpen = null, styles = true, keys = true, log = null } = {}) {
+  if (styles) injectMenuStyles();
+  let cur = null;   // { menu, ctx, resolve, sel, busy, hint }
+  let el = null;
+  function box() {
+    if (el) return el;
+    el = document.getElementById(id);
+    if (!el) {
+      el = document.createElement('div'); el.id = id; el.className = 'menu-box'; el.setAttribute('role', 'dialog'); el.hidden = true;
+      (parent || document.body).appendChild(el);
+    }
+    el.addEventListener('click', e => {
+      const b = e.target.closest('[data-menu-item]'); if (b) { choose(+b.dataset.menuItem, 'click'); return; }
+      if (e.target.closest('[data-menu-close]')) close();
+    });
+    el.addEventListener('mousemove', e => { const b = e.target.closest('[data-menu-item]'); if (b && cur && +b.dataset.menuItem !== cur.sel) { cur.sel = +b.dataset.menuItem; mark(); } });
+    return el;
+  }
+  function render() {
+    const el = box(); if (!cur) { el.hidden = true; return; }
+    const m = cur.menu;
+    el.innerHTML = `<div class="menu-head"><b>${esc(m.title || cur.ctx.title || '')}</b><button type="button" class="menu-x" data-menu-close aria-label="close">✕</button></div>`
+      + (m.text ? `<p class="menu-text">${esc(m.text)}</p>` : '')
+      + `<ol class="menu-items">${m.items.map((i, n) => `<li><button type="button" data-menu-item="${n}" class="${n === cur.sel ? 'sel' : ''}"><span class="menu-num">${n + 1}</span>${esc(i.label)}</button></li>`).join('')}</ol>`
+      + `<div class="menu-hint" aria-live="polite">${esc(cur.hint || `click, press 1-${Math.min(9, m.items.length)}, or type or say it${m.other ? ' (or anything else)' : ''} · Esc closes`)}</div>`;
+    el.hidden = false;
+    el.setAttribute('aria-label', m.title || 'menu');
+  }
+  function mark() { box().querySelectorAll('[data-menu-item]').forEach(b => b.classList.toggle('sel', +b.dataset.menuItem === cur?.sel)); }
+  function hint(text) { if (!cur) return; cur.hint = text; const h = box().querySelector('.menu-hint'); if (h) h.textContent = text; }
+
+  // ctx: anything the caller wants back in onChoose (the Tablefolk game: agentId)
+  function open(menuIn, ctx = {}) {
+    const menu = normalizeMenu(menuIn);
+    if (!menu) { log?.('no such menu', menuIn); return Promise.resolve(null); }
+    if (cur) finish(null);
+    return new Promise(res => {
+      cur = { menu, ctx, resolve: res, sel: 0, hint: '' };
+      render();
+      onOpen?.(menu, ctx);
+    });
+  }
+  function finish(result) { const c = cur; cur = null; render(); c?.resolve(result); }
+  function close() { finish(null); }
+  function choose(n, how, text) {
+    if (!cur) return;
+    const { menu, ctx } = cur, item = menu.items[n]; if (!item) return;
+    finish({ item, how, text: text ?? null });
+    onChoose?.(item, { menu, how, text: text ?? null, ...ctx });
+  }
+  async function offer(text) {
+    if (!cur) return false;
+    if (cur.busy) return true;
+    const c = cur; c.busy = true; hint('working out which one you meant…');
+    let r; try { r = await match(c.menu, text, { log, ...(matchOptions() || {}) }); } finally { c.busy = false; }
+    if (cur !== c) return true;
+    if (r.item) { log?.('matched', JSON.stringify(text), '->', r.item.id, 'by', r.by, r.score ?? ''); choose(c.menu.items.findIndex(i => i.id === r.item.id), 'words', text); return true; }
+    if (c.menu.other) { finish({ other: true, text }); onOther?.(text, c.menu, c.ctx); return true; }
+    if (r.unsure?.length > 1) {
+      const nums = r.unsure.map(i => c.menu.items.findIndex(x => x.id === i.id) + 1);
+      c.sel = nums[0] - 1; mark();
+      hint(`did you mean ${r.unsure.map((i, k) => `${nums[k]}. "${i.label}"`).join(' or ')}? Press its number, or say it another way`);
+      return true;
+    }
+    hint(`"${String(text).slice(0, 50)}" isn't one of these: pick one, or say it another way`);
+    return true;
+  }
+  // keys while a menu is open (not while typing in a field)
+  const onKey = e => {
+    if (!cur) return;
+    const typing = /^(INPUT|TEXTAREA|SELECT)$/.test(document.activeElement?.tagName || '') || document.activeElement?.isContentEditable;
+    if (e.key === 'Escape') { e.preventDefault(); e.stopImmediatePropagation(); close(); return; }
+    if (typing) return;
+    const n = cur.menu.items.length;
+    if (/^[1-9]$/.test(e.key) && +e.key <= n) { e.preventDefault(); e.stopImmediatePropagation(); choose(+e.key - 1, 'key'); return; }
+    if (e.key === 'ArrowDown' || e.key === 'ArrowUp') { e.preventDefault(); e.stopImmediatePropagation(); cur.sel = (cur.sel + (e.key === 'ArrowDown' ? 1 : n - 1)) % n; mark(); return; }
+    if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); e.stopImmediatePropagation(); choose(cur.sel, 'key'); }
+  };
+  if (keys) addEventListener('keydown', onKey, true);
+  return {
+    open, close, offer, choose, hint,
+    get active() { return cur ? cur.menu : null; },
+    get context() { return cur ? cur.ctx : null; },
+    destroy() { removeEventListener('keydown', onKey, true); close(); el?.remove(); },
+  };
+}

package/index.js

@@ -0,0 +1,108 @@
+// @tablefolk/menus -- JRPG-style menus: a list of choices a player clicks,
+// presses a number for, types, or says. This module is the matching (no DOM);
+// box.js is the menu box on screen.
+//
+// A menu:
+//   { id: 'smith', title: 'Brakka', text: 'What do you need?',
+//     items: [ { id: 'buy', label: 'Buy a sword (30 gold)', say: 'I would like to buy a sword.' },
+//              { id: 'ask', label: 'Ask about the wolves', keywords: ['wolf', 'wolves'] },
+//              { id: 'bye', label: 'Leave' } ],
+//     other: true }          // words that fit no choice are passed on (else "not understood")
+// Items may carry any other fields (the Tablefolk game uses say, do, menu).
+//
+// Words are matched to a choice in steps, cheapest first: a number ("2",
+// "two", "the second one", "the last"), the label or a keyword, shared words,
+// then meaning (an embedding model, when given and its best choice is clear),
+// then a language model asked to pick a number. Every step can answer "none".
+//
+//   import { match, normalizeMenu, modelChooser } from '@tablefolk/menus';
+//   await match(menu, 'can you fix my blade', {
+//     embed: async (query, texts) => texts.map(t => cosine(...)),     // optional
+//     choose: modelChooser(async (messages, opts) => text),           // optional: any chat model
+//   })  -> { item, by: 'number'|'label'|'keyword'|'words'|'meaning'|'model', score } | { none: true, by }
+//          (none with unsure: [items]: meaning found a few close choices and nothing decided between them)
+
+export const norm = s => String(s || '').toLowerCase().replace(/[’']/g, '').replace(/[^a-z0-9 ]+/g, ' ').replace(/\s+/g, ' ').trim();
+const STOP = new Set('a an the to of and or i im me my you your we us it is are be do can could would will want like please some about for with on in at this that these those what whats one just get got let lets go ok okay yes no have need'.split(' '));
+// content words, roughly stemmed ("repaired", "repairs", "repairing" -> "repair")
+const stem = w => w.length > 5 && /(ing|ed)$/.test(w) ? w.replace(/(ing|ed)$/, '') : w.length > 3 ? w.replace(/ies$/, 'y').replace(/(es|s)$/, '') : w;
+export const words = s => norm(s).split(' ').filter(w => w.length > 2 && !STOP.has(w)).map(stem);
+const NUM = { one: 1, two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9, first: 1, second: 2, third: 3, fourth: 4, fifth: 5, sixth: 6, seventh: 7, eighth: 8, ninth: 9, last: -1 };
+// embedding cosine (calibrated on EmbeddingGemma, a query against "label. say"):
+// the best must reach EMBED_MIN and lead the next by EMBED_GAP, else the model decides
+export const EMBED_MIN = 0.74, EMBED_GAP = 0.06;   // unrelated choices score 0.6-0.7 (2026-11-12: right picks 0.76-0.91)
+
+// a usable copy: items with ids and labels, at most 24
+export function normalizeMenu(menu) {
+  if (!menu || !Array.isArray(menu.items) || !menu.items.length) return null;
+  return { ...menu, items: menu.items.filter(i => i && (i.label || i.say)).slice(0, 24).map((i, n) => ({ ...i, id: String(i.id || 'item' + (n + 1)), label: String(i.label || i.say) })) };
+}
+export const itemText = i => [i.label, i.say].filter(Boolean).join('. ');
+
+export async function match(menuIn, text, { embed = null, choose = null, embedMin = EMBED_MIN, embedGap = EMBED_GAP, log = null } = {}) {
+  const menu = normalizeMenu(menuIn); if (!menu) return { none: true, by: 'no menu' };
+  const items = menu.items, t = norm(text);
+  if (!t) return { none: true, by: 'empty' };
+  // a number: "2", "number 2", "option two", "the second one", "the last"
+  const num = t.match(/^(?:(?:number|option|choice|the)\s+)?(\d+|[a-z]+)(?:\s+(?:one|option|choice|please))?$/);
+  if (num) {
+    let n = /^\d+$/.test(num[1]) ? +num[1] : NUM[num[1]];
+    if (n === -1) n = items.length;
+    if (n >= 1 && n <= items.length) return { item: items[n - 1], by: 'number', score: 1 };
+  }
+  // the label itself, or one of its keywords
+  for (const i of items) if (norm(i.label) === t || norm(i.say) === t) return { item: i, by: 'label', score: 1 };
+  const kw = items.filter(i => (i.keywords || []).some(k => new RegExp('\\b' + norm(k).replace(/ /g, '\\s+') + '\\b').test(t)));
+  if (kw.length === 1) return { item: kw[0], by: 'keyword', score: 1 };
+  // shared words: most of a choice's words said, and more than any other choice
+  const tw = new Set(words(t));
+  const overlap = items.map(i => { const iw = [...new Set(words(i.label))]; return iw.length ? iw.filter(w => tw.has(w)).length / iw.length : 0; });
+  const best = Math.max(...overlap), at = overlap.indexOf(best);
+  if (best >= 0.6 && overlap.filter(v => v === best).length === 1) return { item: items[at], by: 'words', score: best };
+  // meaning: an embedding model, when its pick is clear
+  let unsure = null;
+  if (embed) {
+    try {
+      const texts = items.map(itemText), r = await embed(text, texts);
+      if (r) {
+        const sims = r instanceof Map ? texts.map(x => r.get(x) ?? 0) : [...r];
+        const scored = sims.map((s, n) => [s, n]).sort((a, b) => b[0] - a[0]);
+        const [s1, n1] = scored[0], s2 = scored[1]?.[0] ?? 0;
+        log?.('meaning', text, scored.map(([s, n]) => items[n].id + ' ' + s.toFixed(2)).join(', '));
+        if (s1 >= embedMin && s1 - s2 >= embedGap) return { item: items[n1], by: 'meaning', score: +s1.toFixed(3) };
+        // close between the best few: the model decides, or (without one) the player is asked
+        if (s1 >= embedMin) unsure = scored.filter(([s]) => s >= embedMin && s1 - s < embedGap).slice(0, 3).map(([, n]) => items[n]);
+      }
+    } catch (e) { log?.('embedding failed', e); }
+  }
+  // a language model picks a number
+  if (choose) {
+    const p = await choose(menu.text || menu.title || 'Which choice?', items.map(i => i.label), { context: 'The player said: "' + String(text).slice(0, 300) + '"' });
+    if (p && p.index >= 0) return { item: items[p.index], by: p.by || 'model', score: p.confidence ?? null };
+    return { none: true, by: p ? p.by || 'model' : 'no match', ...(unsure && !p ? { unsure } : {}) };
+  }
+  return unsure ? { none: true, by: 'unsure', unsure } : { none: true, by: 'no match' };
+}
+
+// A chooser from any chat model: generate(messages, { maxTokens, temperature })
+// resolves the reply's text. It asks for one number, greedily.
+//   choose(question, options, { context, none = true }) -> { index (-1: none), by } | null on failure
+export function modelChooser(generate, { log = null } = {}) {
+  return async function choose(question, options, { context = '', none = true } = {}) {
+    if (!options?.length) return null;
+    const list = options.map((o, n) => `${n + 1}. ${o}`).join('\n') + (none ? '\n0. None of these' : '');
+    const prompt = `${context ? context + '\n\n' : ''}${question}\nChoices:\n${list}\n\nWhich choice is meant? Answer with the number only.`;
+    try {
+      const out = String(await generate([
+        { role: 'system', content: 'You match what a player said to one choice of a game menu. Answer with one number and nothing else.' },
+        { role: 'user', content: prompt }], { maxTokens: 6, temperature: 0 }) || '');
+      log?.('model', JSON.stringify(out));
+      const m = out.match(/\d+/);
+      if (!m) return { index: -1, by: 'model (no number)' };
+      const n = +m[0];
+      return { index: n >= 1 && n <= options.length ? n - 1 : -1, by: 'model' };
+    } catch (e) { log?.('model failed', e); return null; }
+  };
+}
+
+export { createMenuBox, injectMenuStyles } from './box.js';

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@tablefolk/menus",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "JRPG-style menus: click, press a number, type or say a choice; words matched by number, label, keywords, meaning (embeddings) or a language model.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./*": "./*"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/runvnc/tablefolk.git",
+    "directory": "libs/menus"
+  },
+  "homepage": "https://github.com/runvnc/tablefolk/tree/main/libs/menus",
+  "keywords": [
+    "tablefolk",
+    "browser",
+    "menu",
+    "game",
+    "rpg",
+    "speech",
+    "llm"
+  ],
+  "sideEffects": false
+}