@tablefolk/script 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,128 @@
-# Temporary Holding Version
+# @tablefolk/script
 
-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.
+Scripted stories for games and chat apps: world **flags** and the **facts**
+characters know while they hold, one **condition** language, **actions**, a
+step **runner** for workflows, **triggers**, and a **validator**. It has no
+DOM and no game in it: your app supplies a small host (who carries what, run
+a character's command, what was said to it, optionally a language model). It
+runs in the browser and in Node.
+
+Tablefolk uses it for menus, workflows and model-free worlds, through
+`app/story.js` in the repository.
+
+## Conditions and templates
+
+```
+world.cat_found                     a flag holds (not false, 0, "", "no", "none", "off")
+world.favours >= 2                  == != >= <= > <  contains
+player has lost cat                 someone carries it (player lacks ...)
+player has "bread and butter"       quote names that contain and/or
+player.gold >= 10, me.gold, bert.items contains key
+answer contains kettle              a workflow run's own variables
+not world.paid, (a or b) and c      not / and / or, brackets ("and" binds first)
+```
+
+- **Item names match whole words:** "cat" finds "lost cat", but "key" doesn't
+  find "keyring".
+- **Templates:** `{{player}}`, `{{me}}`, `{{world.flag}}`, `{{player.gold}}`,
+  and run variables.
+- **Errors:** `parse()` throws `ExprError` with a position.
+
+## Actions
+
+A menu choice, a workflow's `do` step and a trigger's `do` are one list of
+effects, run in this order:
+
+| effect | example |
+|---|---|
+| `take` | `"take": "lost cat"` |
+| `set` | `"set": {"cat_found": true, "favours": "+1"}` |
+| `say` | the player's line |
+| `reply` | the character's line |
+| `act` | command lines: `"act": ["give(silver locket)"]` |
+| `give` | `"give": "pie"` |
+| `start` | a workflow: `"start": "riddle"` (also `workflow`) |
+| `stop` | `"stop": true` |
+
+`world.x` is always a flag. A bare name is a flag in a menu or a trigger, and
+a run variable inside a workflow.
+
+## Workflows (the runner)
+
+Step types:
+
+| step | what it does |
+|---|---|
+| `await` | waits for `"speech"`, or for `"turns"` |
+| `set` | sets run variables or flags |
+| `take` | the player hands an item over, with `"else"` when they don't carry it |
+| `if` / `then` / `else` | branches on a condition |
+| `choose` | `"by": ["decider", "model", "default"]`, the order of who answers |
+| `prompt` | a question for the model |
+| `command` | a command line; takes the character's turn |
+| `menu` | the player picks; `"options"` maps a choice id to a step, words that fit no choice go to `"other"` (or the menu asks again), closing goes to `"closed"` |
+| `do` | actions (above) |
+
+Any step can also have `goto`, `end`, and `max` + `exit`.
+
+A saved run keeps the step's **id** and a version, so it survives edits to
+the scenario. Runs pause and resume (a menu opened mid-workflow).
+`advance(id, { until: 'turn' })` stops after a command that took the
+character's turn; `until: 'wait'` runs on until the flow waits.
+
+## Triggers
+
+```json
+"triggers": [ { "on": "flag", "flag": "cat_found", "to": true, "as": "bert", "once": true, "do": { "reply": "Whiskers is home!" } },
+              { "on": "given", "who": "pell", "item": "lost cat", "do": { "set": { "cat_found": true } } },
+              { "on": "start", "as": "hobb", "do": { "start": "open_shop" } } ]
+```
+
+- **Optional fields:** `if` and `once`.
+- **No chains:** a trigger set off while another runs is skipped, so they
+  can't loop.
+
+## Validate
+
+`validate(scenario)` returns `[{ level, where, message }]`. It finds:
+- conditions that don't parse;
+- `goto`/`then`/`other` targets that don't exist, and steps nothing reaches;
+- menus and workflows that are named but missing;
+- flags that are read but never set;
+- in a world with no model: a `choose` without a default, and a menu step
+  without `other`.
+
+Tablefolk's world generator sends the errors back to its model to fix.
+
+## Use
+
+```js
+import { createState, createRunner, createTriggers, perform, visibleMenu, pickMenu, check, validate, memoryHost } from '@tablefolk/script';
+
+const host = memoryHost({ player: { gold: 10, items: [] }, chars: { bert: { inventory: { items: ['lost cat'] } } } });
+const flags = {}, state = createState({ flags: () => flags, facts: () => scenario.facts }); host._state = state;
+const runs = {}, store = { get: id => runs[id] || null, set: (id, r) => { if (r) runs[id] = r; else delete runs[id]; } };
+const runner = createRunner({ flows: () => scenario.workflows, state, host, store });
+const triggers = createTriggers({ list: () => scenario.triggers, state, host, runner });
+
+await perform(menuItem, { host, state, me: 'pell', runner, triggers });   // a menu choice
+runner.start('hobb', 'riddle'); await runner.advance('hobb', { until: 'wait' });
+host.heard.hobb = ['a kettle']; await runner.advance('hobb', { until: 'wait' });
+```
+
+A host for your own app implements:
+
+| method | what it does |
+|---|---|
+| `scope(me, vars)` | gives conditions access to `inventory(who)`, `playerName()` and `flag(name)` |
+| `transfer(from, to, item)` | moves an item from one holder to another |
+| `run(actorId, line)` | runs a command line as a character; returns `{ tookTurn }` |
+| `hear(actorId)` | what was said to the character since it last listened |
+| `ask(actorId, question, parse, options)` | asks the model; null when there is none |
+
+Optional: `decide`, `menu(actorId, ref)`, `playerSays`, `log`, `ended`.
+
+Tests: `node test.mjs` (35 checks, including a full playthrough of
+Tablefolk's Willow Lane with no model).
+
+Part of [Tablefolk](https://github.com/runvnc/tablefolk) (`libs/`). MIT.

package/actions.js

@@ -0,0 +1,73 @@
+// What a menu choice, a workflow step ("do") or a trigger does. One list of
+// effects, run in this order:
+//   take      the player hands this item to the character (stops here when they lack it)
+//   set       flags: { "cat_found": true, "favours": "+1" } (world.x is always a flag;
+//             a bare name is a flag here, a run variable inside a workflow)
+//   say       the player's line (shown; the host decides who hears it)
+//   reply     the character says this
+//   act       command lines the character runs: "give(silver locket)", "walk(well)" (a string or a list)
+//   give      the character hands the player this item (a give() command)
+//   start     starts a workflow on the character: "riddle" or { "name": "riddle", "input": "..." }
+//             ("workflow": the same, the name menus used first)
+//   stop      stops the character's workflow (true)
+// Texts take {{player}}, {{me}}, {{world.flag}}, {{player.gold}}, run variables.
+//
+//   await perform(actions, { host, state, me, vars, runner, triggers }) -> { ok, missing?, started? }
+// host: { run(actorId, line) -> Promise<{ tookTurn }>, transfer(from, to, item) -> bool,
+//         playerSays?(actorId, text), scope(me, vars) -> expr scope }
+import { render, applyValue, findItem } from './expr.js';
+
+// "+1" adds to what was there; "3+1" (a rendered "{{tries}}+1") is worked out
+export function arith(was, v) {
+  const m = typeof v === 'string' && v.match(/^\s*(-?\d+(?:\.\d+)?)\s*([+-])\s*(-?\d+(?:\.\d+)?)\s*$/);
+  return m ? (m[2] === '+' ? +m[1] + +m[3] : +m[1] - +m[3]) : applyValue(was, v);
+}
+
+const q = s => '"' + String(s).replace(/"/g, "'") + '"';
+export async function perform(a, ctx) {
+  if (!a) return { ok: true };
+  const { host, state, me, vars = {}, runner = null, triggers = null } = ctx;
+  const scope = host.scope(me, vars), t = x => render(x, scope);
+  if (a.take != null) {
+    const item = t(a.take);
+    if (!host.transfer('player', me, item)) return { ok: false, missing: item };
+    triggers?.fire('given', { who: me, item, from: 'player' });
+  }
+  for (const [k, v] of Object.entries(a.set || {})) {
+    // world.x is always a flag; a bare name is a flag in a menu or trigger, a run variable in a workflow
+    if (/^world\./i.test(k) || !ctx.inRun) state.set(k, typeof v === 'string' ? t(v) : v);
+    else vars[k] = arith(vars[k], typeof v === 'string' ? t(v) : v);
+  }
+  if (a.say != null) host.playerSays?.(me, t(a.say));
+  const lines = [];
+  if (a.reply != null) lines.push(`say(${q(t(a.reply))})`);
+  for (const l of [].concat(a.act ?? [])) lines.push(t(l));
+  if (a.give != null) lines.push(`give(${t(a.give)})`);
+  for (const line of lines) if (me) await host.run(me, line);
+  if (a.stop && runner && me) runner.stop(me, 'stopped');
+  let started = null;
+  const startRef = a.start ?? a.workflow;   // "workflow": the menu field's older name
+  if (startRef != null && runner && me) {
+    const s = typeof startRef === 'string' ? { name: startRef } : startRef;
+    if (runner.start(me, t(s.name), s.input != null ? t(s.input) : (a.say ?? ''))) started = s.name;
+  }
+  return { ok: true, started };
+}
+
+// The choices of a menu that show now: their "if" holds, and a "take" item is
+// carried by the player. Labels, says, title and text rendered.
+//   visibleMenu(menu, scope) -> menu with items filtered (scope from host.scope(me, {}))
+import { check } from './expr.js';
+export function visibleMenu(menu, scope) {
+  if (!menu || !Array.isArray(menu.items)) return menu || null;
+  const inv = scope.inventory?.('player');
+  const items = menu.items.filter(i => i && check(i.if, scope) && (i.take == null || !inv || findItem(inv.items, render(i.take, scope))))
+    .map(i => ({ ...i, label: render(i.label || i.say, scope), ...(i.say != null ? { say: render(i.say, scope) } : {}) }));
+  return { ...menu, ...(menu.title ? { title: render(menu.title, scope) } : {}), ...(menu.text ? { text: render(menu.text, scope) } : {}), items };
+}
+// a character's menu: an id or object, or a list whose first entry with a holding "if" wins
+export function pickMenu(ref, menus, scope) {
+  if (Array.isArray(ref)) { const hit = ref.find(m => m && check(m.if, scope)); return hit ? pickMenu(hit.menu ?? hit, menus, scope) : null; }
+  if (typeof ref === 'string') return menus?.[ref] ? { id: ref, ...menus[ref] } : null;
+  return ref || null;
+}

package/expr.js

@@ -0,0 +1,146 @@
+// Conditions and templates: one language for menus, workflows, triggers and goals.
+//
+//   world.cat_found                     a flag holds (not false, 0, "", "no", "none", "off")
+//   world.favours >= 2                  compare: == != >= <= > <  contains
+//   player has lost cat                 someone carries it   (player lacks lost cat)
+//   player has "bread and butter"       quote names that contain and/or
+//   player.gold >= 10, me.gold, bert.items contains key
+//   answer contains kettle              a run's own variables
+//   not world.paid, (a or b) and c      not / and / or, brackets
+//
+// Item names match whole words: "cat" finds "lost cat", "key" does not find "keyring".
+//
+//   const ast = parse('player has lost cat and not world.paid');   // throws ExprError (with .pos) on bad input
+//   evaluate(ast, scope) / check(text, scope) -> boolean
+//   render('Thanks, {{player}}! You have {{player.gold}} gold.', scope)
+// scope: { flag(name), vars: {}, me, playerName(), inventory(who) -> { gold, items: [{ name, qty }] } | null }
+
+export class ExprError extends Error { constructor(msg, pos, text) { super(`${msg} at ${pos} in "${text}"`); this.pos = pos; this.text = text; } }
+
+const OPS = ['==', '!=', '>=', '<=', '>', '<'];
+function tokenize(text) {
+  const out = []; let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    if (/\s/.test(c)) { i++; continue; }
+    if (c === '"' || c === "'") {
+      const end = text.indexOf(c, i + 1); if (end < 0) throw new ExprError('unclosed quote', i, text);
+      out.push({ t: 'str', v: text.slice(i + 1, end), pos: i }); i = end + 1; continue;
+    }
+    if (c === '(' || c === ')') { out.push({ t: c, pos: i }); i++; continue; }
+    if (c === '!' && text[i + 1] !== '=') { out.push({ t: 'not', pos: i }); i++; continue; }
+    const op = OPS.find(o => text.startsWith(o, i)); if (op) { out.push({ t: 'op', v: op, pos: i }); i += op.length; continue; }
+    const m = text.slice(i).match(/^[^\s()"'=!<>]+/);
+    const w = m[0], low = w.toLowerCase();
+    if (low === 'and' || low === 'or' || low === 'not') out.push({ t: low, pos: i });
+    else if (low === 'contains') out.push({ t: 'op', v: 'contains', pos: i });
+    else if (low === 'has' || low === 'lacks' || low === 'carries') out.push({ t: 'has', v: low === 'lacks' ? 'lacks' : 'has', pos: i });
+    else out.push({ t: 'word', v: w, pos: i });
+    i += w.length;
+  }
+  return out;
+}
+
+export function parse(text) {
+  text = String(text ?? '').trim();
+  if (!text) return { k: 'lit', v: true };
+  const toks = tokenize(text); let p = 0;
+  const peek = () => toks[p], take = t => { const x = toks[p]; if (!x || (t && x.t !== t)) throw new ExprError(`expected ${t || 'more'}`, x ? x.pos : text.length, text); p++; return x; };
+  const stop = x => !x || x.t === 'and' || x.t === 'or' || x.t === ')';
+  // words up to and/or/): an item name or a right-hand side ("lost cat")
+  function phrase() {
+    const x = peek(); if (!x || stop(x)) throw new ExprError('expected a value', x ? x.pos : text.length, text);
+    if (x.t === 'str') { p++; return { k: 'lit', v: x.v }; }
+    const words = []; while (peek() && !stop(peek()) && peek().t === 'word') words.push(take().v);
+    if (!words.length) throw new ExprError('expected a value', x.pos, text);
+    if (words.length === 1) return /^-?\d+(\.\d+)?$/.test(words[0]) ? { k: 'lit', v: +words[0] } : { k: 'ref', v: words[0] };
+    return { k: 'lit', v: words.join(' ') };
+  }
+  function primary() {
+    const x = peek();
+    if (!x) throw new ExprError('unexpected end', text.length, text);
+    if (x.t === 'not') { p++; return { k: 'not', a: primary() }; }
+    if (x.t === '(') { p++; const e = or(); take(')'); return e; }
+    // holder has item
+    if (x.t === 'word' && toks[p + 1]?.t === 'has') { p++; const h = take('has'); return { k: 'has', who: x.v, item: phrase(), neg: h.v === 'lacks' }; }
+    const a = x.t === 'str' ? (p++, { k: 'lit', v: x.v }) : x.t === 'word' ? (p++, /^-?\d+(\.\d+)?$/.test(x.v) ? { k: 'lit', v: +x.v } : { k: 'ref', v: x.v }) : null;
+    if (!a) throw new ExprError(`unexpected "${x.v || x.t}"`, x.pos, text);
+    if (peek()?.t === 'op') { const op = take().v; return { k: 'cmp', op, a, b: phrase() }; }
+    return { k: 'truthy', a };
+  }
+  function and() { let e = primary(); while (peek()?.t === 'and') { p++; e = { k: 'and', a: e, b: primary() }; } return e; }
+  function or() { let e = and(); while (peek()?.t === 'or') { p++; e = { k: 'or', a: e, b: and() }; } return e; }
+  const e = or();
+  if (p < toks.length) throw new ExprError(`unexpected "${toks[p].v || toks[p].t}"`, toks[p].pos, text);
+  return e;
+}
+
+export const truthy = v => v != null && v !== false && !/^(|0|no|false|none|off)$/i.test(String(v).trim());
+const norm = s => String(s ?? '').toLowerCase().replace(/^(a|an|the|some)\s+/, '').trim();
+// whole words: "cat" finds "lost cat", "key" does not find "keyring"
+export function itemMatches(name, want) {
+  const n = norm(name), w = norm(want); if (!n || !w) return false;
+  if (n === w) return true;
+  const re = s => new RegExp('(^|\\W)' + s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '(\\W|$)');
+  return re(w).test(n) || re(n).test(w);
+}
+export function findItem(items, want) {
+  const live = (items || []).map(i => typeof i === 'string' ? { name: i, qty: 1 } : i).filter(i => i && (i.qty ?? 1) > 0);
+  return live.find(i => norm(i.name) === norm(want)) || live.find(i => itemMatches(i.name, want)) || null;
+}
+
+// a name's value: world.x (a flag), <who>.gold / <who>.items, a run variable, else the word itself
+export function lookup(name, scope = {}) {
+  const n = String(name);
+  if (/^world\./i.test(n)) return scope.flag?.(n.slice(6));
+  const m = n.match(/^([\w-]+)\.(gold|items)$/i);
+  if (m) {
+    const inv = scope.inventory?.(m[1] === 'me' ? scope.me : m[1]);
+    if (inv) return m[2].toLowerCase() === 'gold' ? Number(inv.gold) || 0 : (inv.items || []).filter(i => (i.qty ?? 1) > 0).map(i => i.name).join(', ');
+  }
+  if (n === 'me') return scope.me ?? '';
+  if (n === 'player') return scope.playerName?.() ?? 'the player';
+  if (scope.vars && n in scope.vars) { const v = scope.vars[n]; return /^\s*-?\d+(\.\d+)?\s*$/.test(String(v)) ? +v : v; }
+  return n;
+}
+
+export function evaluate(e, scope = {}) {
+  const val = x => x.k === 'lit' ? x.v : lookup(x.v, scope);
+  switch (e.k) {
+    case 'lit': return truthy(e.v);
+    case 'not': return !evaluate(e.a, scope);
+    case 'and': return evaluate(e.a, scope) && evaluate(e.b, scope);
+    case 'or': return evaluate(e.a, scope) || evaluate(e.b, scope);
+    case 'truthy': return truthy(val(e.a));
+    case 'has': { const inv = scope.inventory?.(e.who === 'me' ? scope.me : e.who); const r = !!(inv && findItem(inv.items, val(e.item.k === 'ref' ? { k: 'lit', v: e.item.v } : e.item))); return e.neg ? !r : r; }
+    case 'cmp': {
+      const a = val(e.a), b = e.b.k === 'ref' && !/^world\.|\.(gold|items)$/i.test(e.b.v) && !(scope.vars && e.b.v in scope.vars) ? e.b.v : val(e.b);
+      if (e.op === 'contains') return String(a ?? '').toLowerCase().includes(String(b ?? '').toLowerCase());
+      const num = x => typeof x === 'number' ? x : /^\s*-?\d+(\.\d+)?\s*$/.test(String(x)) ? +x : (x === true ? 1 : x === false || x == null ? 0 : NaN);
+      const na = num(a), nb = num(b), both = !Number.isNaN(na) && !Number.isNaN(nb);
+      const x = both ? na : String(a ?? '').toLowerCase(), y = both ? nb : String(b ?? '').toLowerCase();
+      return e.op === '==' ? x == y : e.op === '!=' ? x != y : e.op === '>=' ? x >= y : e.op === '<=' ? x <= y : e.op === '>' ? x > y : x < y;
+    }
+  }
+  return false;
+}
+const cache = new Map();
+export function check(text, scope = {}) {
+  if (text == null || text === '' || text === true) return true;
+  if (text === false) return false;
+  if (Array.isArray(text)) return text.every(t => check(t, scope));
+  let ast = cache.get(text); if (!ast) { ast = parse(text); if (cache.size > 500) cache.clear(); cache.set(text, ast); }
+  return evaluate(ast, scope);
+}
+export function render(tpl, scope = {}) {
+  return String(tpl ?? '').replace(/\{\{\s*([\w.-]+)\s*\}\}/g, (_, k) => { const v = lookup(k, scope); return v == null || v === k && !(scope.vars && k in scope.vars) && k !== 'me' && k !== 'player' ? '' : String(v); });
+}
+// "+1" / "-2" add to a number; "true"/"false" and numbers become themselves
+export function applyValue(was, value) {
+  if (typeof value !== 'string') return value;
+  const m = value.match(/^\s*([+-])\s*(\d+(?:\.\d+)?)\s*$/);
+  if (m) return (Number(was) || 0) + (m[1] === '+' ? +m[2] : -m[2]);
+  if (/^\s*-?\d+(\.\d+)?\s*$/.test(value)) return +value;
+  if (value === 'true') return true; if (value === 'false') return false;
+  return value;
+}

package/index.js

@@ -0,0 +1,48 @@
+// @tablefolk/script -- scripted stories: world flags and facts, one condition
+// language, actions, a step runner for workflows (menus as steps the player
+// answers), triggers, and a validator. No DOM and no game: the app gives a
+// small host (who carries what, run a character's command, what was said).
+// Runs in the browser and in Node. README.md has the scenario format.
+//
+//   import { createState, createRunner, createTriggers, perform, check, render, validate } from '@tablefolk/script';
+export { parse, evaluate, check, render, lookup, truthy, itemMatches, findItem, applyValue, ExprError } from './expr.js';
+export { createState } from './state.js';
+export { perform, arith, visibleMenu, pickMenu } from './actions.js';
+export { createRunner, parseAnswer, RUN_VERSION } from './run.js';
+export { createTriggers } from './triggers.js';
+export { validate } from './validate.js';
+
+// A plain in-memory host (tests, tools, a text adventure): inventories and a
+// say log; run() understands say("..."), give(item), sell("item", n).
+export function memoryHost({ player = { gold: 0, items: [] }, chars = {}, playerName = 'Traveller' } = {}) {
+  const inv = who => (who === 'player' || who === 'you' ? player : chars[who]?.inventory) || null;
+  const said = [], heard = {};
+  const norm = i => typeof i === 'string' ? { name: i, qty: 1 } : i;
+  const move = (from, to, name) => {
+    const a = inv(from), b = inv(to); if (!a || !b) return false;
+    a.items = (a.items || []).map(norm); b.items = (b.items || []).map(norm);
+    const it = a.items.find(i => (i.qty ?? 1) > 0 && (i.name.toLowerCase() === String(name).toLowerCase() || new RegExp('(^|\\W)' + String(name).toLowerCase() + '(\\W|$)').test(i.name.toLowerCase())));
+    if (!it) return false;
+    if ((it.qty ?? 1) > 1) it.qty--; else a.items.splice(a.items.indexOf(it), 1);
+    const have = b.items.find(i => i.name === it.name); if (have) have.qty = (have.qty || 1) + 1; else b.items.push({ name: it.name, qty: 1 });
+    return it.name;
+  };
+  const host = {
+    player, chars, said, heard,
+    scope: (me, vars) => ({ me, vars, playerName: () => playerName, inventory: inv, flag: n => host._state?.get(n) }),
+    transfer: (from, to, item) => !!move(from, to, item),
+    async run(actor, line) {
+      let m;
+      if ((m = line.match(/^say\("(.*)"\)$/s))) said.push(`${actor}: ${m[1]}`);
+      else if ((m = line.match(/^give\((.+)\)$/))) move(actor, 'player', m[1].replace(/^["']|["']$/g, ''));
+      else if ((m = line.match(/^sell\("(.+)",\s*(\d+)\)$/))) { if ((player.gold || 0) >= +m[2] && move(actor, 'player', m[1])) { player.gold -= +m[2]; inv(actor).gold = (inv(actor).gold || 0) + +m[2]; } }
+      else said.push(`${actor} does: ${line}`);
+      return { tookTurn: true };
+    },
+    hear: actor => { const q = heard[actor]; return q?.length ? q.shift() : null; },
+    ask: async () => null,
+    playerSays: (actor, text) => said.push(`player -> ${actor}: ${text}`),
+    log: () => {},
+  };
+  return host;   // set host._state = state so conditions can read flags
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@tablefolk/script",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Scripted stories for games and chat apps: world flags and facts, one condition language, actions, a step runner for workflows (menus as steps the player answers), triggers, and a validator. No DOM; runs in the browser and Node.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./*": "./*"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/runvnc/tablefolk.git",
+    "directory": "libs/script"
+  },
+  "homepage": "https://github.com/runvnc/tablefolk/tree/main/libs/script",
+  "keywords": [
+    "tablefolk",
+    "browser",
+    "dialogue",
+    "workflow",
+    "interactive-fiction",
+    "game",
+    "rpg",
+    "llm"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "test": "node test.mjs"
+  }
+}

package/run.js

@@ -0,0 +1,197 @@
+// The step runner: workflows ("flows") that characters run, one at a time
+// each. A flow is a list of steps; each may have an "id", and the next one
+// follows unless it says "goto", "end", or branches.
+//
+//   await     "speech": the next words addressed to the character ("save" keeps them);
+//             "turns": waits "turns": N turns
+//   set       { "set": { "tries": "{{tries}}+1", "world.paid": true } } run variables; world.x are flags
+//   take      { "take": "lost cat", "else": "stepId" } the player hands it over
+//   if        { "if": "<condition>", "then": "a", "else": "b" } (expr.js)
+//   choose    { "choose": "Fight or flee?", "options": { "fight": "s1", "flee": "s2" },
+//               "by": ["decider", "model", "default"], "default": "flee" }
+//   prompt    { "prompt": "...", "parse": "text|line|number|yesno|word", "save": "x" } (asks the model)
+//   command   { "command": "say(\"hi\")" } a command line; takes the character's turn
+//   menu      { "menu": "bert-sell", "save": "pick", "options": { "pay": "s1" }, "then": "s2",
+//               "other": "s3", "closed": "s4" } the player chooses: an item's id branches by
+//               "options" (else "then"); words that fit none are saved and go to "other"
+//               (else the menu asks again); closing goes to "closed" (else the flow ends)
+//   do        { "do": { "reply": "...", "act": [...], "set": {...}, "give": "..." } } actions.js
+//   goto / end, and "max": N visits then "exit"
+//
+//   const runner = createRunner({ flows: () => scenario.workflows, state, host, store, choosers });
+//   runner.start(actorId, name, input) / stop / active / pause / resume
+//   await runner.advance(actorId, { until: 'turn' | 'wait' }) -> { acted }
+//     'turn': stops after a command that took the character's turn; 'wait': runs on
+//     until the flow waits (speech, turns, its end): a flow started from a menu
+// store: { get(actorId) -> run | null, set(actorId, run | null) } (runs are saved with the world)
+// host: actions.js's, plus hear(actorId) -> text | null, ask(actorId, question, parse, options) ->
+//   text | null (no model: null), decide?(actorId, question, options) -> { choice, confidence },
+//   menu?(actorId, ref) -> { item } | { other, text } | null, log?(text), scope(me, vars)
+// Runs keep the step's id (or "#<index>" for a step without one) and a version,
+// so a saved run survives edits that add or move steps.
+import { check, render, findItem } from './expr.js';
+import { perform, arith } from './actions.js';
+
+export const RUN_VERSION = 2;
+const stepKey = (def, i) => def.steps[i]?.id ?? '#' + i;
+function indexOf(def, ref) {
+  if (ref == null) return -1;
+  if (typeof ref === 'number') return ref;                                   // old saves: an index
+  if (/^#\d+$/.test(ref)) return +ref.slice(1);
+  return def.steps.findIndex(s => s.id === ref);
+}
+function parseAnswer(text, how, options = []) {
+  const t = String(text ?? '').trim();
+  switch (how) {
+    case 'number': { const m = t.replace(/,/g, '').match(/-?\d+(\.\d+)?/); return m ? +m[0] : 0; }
+    case 'yesno': return /^\W*(yes|yeah|yep|sure|ok|okay|true|y)\b/i.test(t) ? 'yes' : 'no';
+    case 'word': return (t.match(/[A-Za-z0-9_-]+/) || [''])[0].toLowerCase();
+    case 'choice': { const low = t.toLowerCase(); return options.find(o => low.startsWith(o.toLowerCase())) || options.find(o => low.includes(o.toLowerCase())) || null; }
+    case 'line': return t.split('\n').map(s => s.trim()).find(Boolean)?.replace(/^say\((.*)\)$/i, '$1').replace(/^["'“]|["'”]$/g, '') || '';
+    default: return t;
+  }
+}
+export { parseAnswer };
+
+export function createRunner({ flows, state, host, store, choosers = ['decider', 'model', 'default'], triggers = null, maxSteps = 40, deciderMin = 0.5 }) {
+  const defs = () => flows() || {};
+  const log = t => host.log?.(t);
+  function start(actor, name, input = '') {
+    const def = defs()[name];
+    if (!def?.steps?.length) { log(`${actor}: no workflow called ${name}`); return false; }
+    const at = def.start != null ? (typeof def.start === 'number' ? stepKey(def, def.start) : def.start) : stepKey(def, 0);
+    store.set(actor, { v: RUN_VERSION, name, at, vars: { input: String(input ?? ''), ...(def.vars || {}) }, visits: {}, wait: 0, paused: false });
+    log(`${actor} [workflow] starts ${name}${input ? ' (' + input + ')' : ''}`);
+    return true;
+  }
+  function stop(actor, why = '') {
+    const run = store.get(actor); if (!run) return;
+    store.set(actor, null);
+    log(`${actor} [workflow] ${run.name} ended${why ? ': ' + why : ''}`);
+    host.ended?.(actor, run);
+  }
+  const active = actor => !!store.get(actor);
+  const pause = actor => { const r = store.get(actor); if (r) { r.paused = true; store.set(actor, r); } };
+  const resume = actor => { const r = store.get(actor); if (r) { r.paused = false; store.set(actor, r); } };
+
+  async function choose(actor, s, run, scope) {
+    const options = Object.keys(s.options || {}), q = render(s.choose, scope);
+    for (const who of [].concat(s.by || choosers)) {
+      if (who === 'default') return s.default ?? options[0];
+      if (who === 'decider' && host.decide) {
+        const r = await host.decide(actor, q, options).catch(() => null);
+        if (r?.choice && (r.confidence ?? 1) >= (s.min ?? deciderMin)) return r.choice;
+      }
+      if (who === 'model') {
+        const text = await host.ask(actor, q, 'choice', options);
+        const p = text == null ? null : parseAnswer(text, 'choice', options);
+        if (p) return p;
+      }
+    }
+    return s.default ?? options[0];
+  }
+
+  // Run steps until the flow waits, ends, or (until: 'turn') a command took the turn.
+  async function advance(actor, { until = 'turn' } = {}) {
+    let acted = false;
+    for (let guard = 0; ; guard++) {
+      const run = store.get(actor); if (!run || run.paused) return { acted };
+      const def = defs()[run.name]; if (!def) { stop(actor, 'definition missing'); return { acted }; }
+      if (run.at === '#end') { stop(actor); return { acted }; }
+      const i = indexOf(def, run.at);
+      if (i < 0 || i >= def.steps.length) { stop(actor, i < 0 && run.at != null ? `step ${run.at} no longer exists` : ''); return { acted }; }
+      if (guard >= maxSteps) { stop(actor, 'too many steps without a pause'); return { acted }; }
+      const s = def.steps[i], key = stepKey(def, i);
+      run.at = key; run.visits[key] = (run.visits[key] || 0) + 1;
+      if (s.max && run.visits[key] > s.max) {
+        if (s.exit == null || indexOf(def, s.exit) < 0) { stop(actor, `step ${key} ran ${s.max} times`); return { acted }; }
+        run.at = s.exit; store.set(actor, run); continue;
+      }
+      const go = ref => { run.at = ref == null ? null : ref; };
+      const next = () => { if (s.end) run.at = '#end'; else if (s.goto != null) run.at = s.goto; else run.at = stepKey(def, i + 1); };
+      const scope = host.scope(actor, run.vars);
+      try {
+        if (s.await) {
+          if (s.await === 'turns') {
+            if (until === 'wait' && (run.wait || 0) + 1 < (+s.turns || 1)) { run.visits[key]--; store.set(actor, run); return { acted }; }
+            run.wait = (run.wait || 0) + 1;
+            if (run.wait < (+s.turns || 1)) { run.visits[key]--; store.set(actor, run); return { acted }; }
+            run.wait = 0; next(); store.set(actor, run); continue;
+          }
+          const heard = host.hear(actor);
+          if (heard == null) { run.visits[key]--; store.set(actor, run); return { acted }; }
+          if (s.save) run.vars[s.save] = heard;
+          next(); store.set(actor, run); continue;
+        }
+        if (s.set) {
+          for (const [k, v] of Object.entries(s.set)) {
+            const val = typeof v === 'string' ? render(v, scope) : v;
+            if (/^world\./i.test(k)) state.set(k, val); else run.vars[k] = arith(run.vars[k], val);
+          }
+          if (s.take == null && s.if == null && s.command == null) { next(); store.set(actor, run); continue; }
+        }
+        if (s.take != null) {
+          const item = render(s.take, scope), ok = host.transfer('player', actor, item);
+          if (ok) triggers?.fire('given', { who: actor, item, from: 'player' });
+          if (s.save) run.vars[s.save] = ok ? 'yes' : 'no';
+          if (!ok && s.else != null) { go(s.else); store.set(actor, run); continue; }
+          next(); store.set(actor, run); continue;
+        }
+        if (s.if != null) {
+          const ok = check(s.if, scope);
+          const to = ok ? s.then : s.else;
+          if (to != null) go(to); else run.at = stepKey(def, i + 1);
+          store.set(actor, run); continue;
+        }
+        if (s.choose != null) {
+          const pickd = await choose(actor, s, run, scope);
+          if (s.save) run.vars[s.save] = pickd;
+          go(s.options?.[pickd] ?? stepKey(def, i + 1)); store.set(actor, run); continue;
+        }
+        if (s.prompt != null) {
+          const text = await host.ask(actor, render(s.prompt, scope), s.parse || 'text');
+          if (s.save) run.vars[s.save] = text == null ? (s.default ?? '') : parseAnswer(text, s.parse || 'text');
+          next(); store.set(actor, run); continue;
+        }
+        if (s.menu != null) {
+          if (!host.menu) { next(); store.set(actor, run); continue; }
+          store.set(actor, run);
+          const r = await host.menu(actor, s.menu);
+          const cur = store.get(actor); if (cur !== run && cur?.name !== run.name) return { acted };   // replaced meanwhile
+          if (!r) { if (s.closed != null) { go(s.closed); store.set(actor, run); continue; } stop(actor, 'menu closed'); return { acted }; }
+          if (r.item) {
+            if (s.save) run.vars[s.save] = r.item.id;
+            go(s.options?.[r.item.id] ?? s.then ?? stepKey(def, i + 1)); store.set(actor, run); acted = true; continue;
+          }
+          if (s.save) run.vars[s.save] = r.text ?? '';
+          if (s.other != null) { go(s.other); store.set(actor, run); continue; }
+          run.visits[key]--; store.set(actor, run); continue;   // asks again
+        }
+        if (s.do != null) {
+          const r = await perform(s.do, { host, state, me: actor, vars: run.vars, runner: api, triggers, inRun: true });
+          if (r.started) return { acted: true };   // another flow replaced this one
+          if (!r.ok && s.else != null) { go(s.else); store.set(actor, run); continue; }
+          next(); store.set(actor, run); acted = true; continue;
+        }
+        if (s.command != null) {
+          const line = render(s.command, scope).replace(/"([^"]*)"/g, (m, inner) => '"' + inner.replace(/"/g, "'") + '"');
+          next(); store.set(actor, run);
+          log(`${actor} [workflow] ${line}`);
+          const r = await host.run(actor, line);
+          acted = true;
+          if (run.at === '#end') { stop(actor); return { acted }; }
+          if (until === 'turn' && r?.tookTurn !== false) return { acted };
+          continue;
+        }
+        next(); store.set(actor, run);
+        if (run.at === '#end') { stop(actor); return { acted }; }
+      } catch (e) {
+        stop(actor, 'error: ' + e.message);
+        return { acted };
+      }
+    }
+  }
+  const api = { start, stop, active, pause, resume, advance, get: actor => store.get(actor), describe: () => Object.entries(defs()).map(([n, d]) => `${n}${d.description ? ' (' + d.description + ')' : ''}`) };
+  return api;
+}
+export { findItem };

package/state.js

@@ -0,0 +1,42 @@
+// World flags and the facts that hold while they do.
+//
+//   const state = createState({ flags: () => myFlagsObject, facts: () => scenario.facts });
+//   state.get('cat_found'); state.set('favours', '+1'); state.all()
+//   state.on(({ name, value, was }) => ...)       every change
+//   state.facts(meId, scope) -> texts            facts whose flag holds, for this character
+// flags: where the values live (an object you save with your world; changed in
+// place). Names may be written world.x or x: the same flag either way.
+// Keys starting with "__" are the library's own (triggers fired once).
+import { applyValue, truthy, render } from './expr.js';
+
+export function createState({ flags = null, facts = () => ({}) } = {}) {
+  let own = {};
+  const store = () => (flags ? flags() : own) || own;
+  const key = n => String(n).replace(/^world\./i, '');
+  const listeners = new Set();
+  return {
+    get: n => store()[key(n)],
+    set(n, value) {
+      const k = key(n), s = store(), was = s[k], v = applyValue(was, value);
+      s[k] = v;
+      for (const fn of listeners) { try { fn({ name: k, value: v, was }); } catch (e) { console.warn('[script] flag listener', e); } }
+      return v;
+    },
+    all: () => Object.fromEntries(Object.entries(store()).filter(([k]) => !k.startsWith('__'))),
+    on(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+    // the facts of flags that hold: "text", or { text, for: [ids] }
+    facts(me, scope = {}) {
+      const out = [];
+      for (const [k, f] of Object.entries(facts() || {})) {
+        if (!truthy(store()[k])) continue;
+        const text = typeof f === 'string' ? f : f?.text; if (!text) continue;
+        if (Array.isArray(f?.for) && !f.for.map(s => String(s).toLowerCase()).includes(String(me).toLowerCase())) continue;
+        out.push(render(text, { ...scope, me }));
+      }
+      return out;
+    },
+    // replace every value (a new world): returns the new object, in case the caller keeps it
+    reset(start = {}) { const s = store(); for (const k of Object.keys(s)) delete s[k]; Object.assign(s, start || {}); return s; },
+    raw: store,
+  };
+}

package/triggers.js

@@ -0,0 +1,49 @@
+// Triggers: things that happen by themselves when the story moves.
+//
+//   "triggers": [
+//     { "on": "flag", "flag": "cat_found", "to": true, "as": "pell", "do": { "reply": "Whiskers is home!" }, "once": true },
+//     { "on": "given", "who": "pell", "item": "lost cat", "do": { "set": { "cat_found": true } } },
+//     { "on": "start", "as": "hobb", "do": { "start": "open_shop" } },
+//     { "on": "flag", "flag": "riddle_solved", "if": "world.cat_found", "as": "hobb", "do": { "act": "emote(dance)" } }
+//   ]
+// on: "flag" (a flag changed; "to": only to that value), "given" (the player
+// handed a character an item; "who", "item" narrow it), "start" (the world
+// began). "if": a condition; "once": at most once per world (remembered in
+// the flags as __fired). "as": the character the actions run as. A trigger
+// set off while another runs is skipped (no chains, no loops).
+//
+//   const triggers = createTriggers({ list: () => scenario.triggers, state, host, runner });
+//   triggers.fire('flag', { name, value }) — state changes are watched for you
+import { check, itemMatches, applyValue } from './expr.js';
+import { perform } from './actions.js';
+
+export function createTriggers({ list, state, host, runner = null }) {
+  let busy = false;
+  const fired = () => (state.raw().__fired ||= []);
+  const api = {
+    async fire(on, data = {}) {
+      if (busy) return;
+      const all = list() || [];
+      const hits = all.map((t, i) => [t, i]).filter(([t, i]) => {
+        if (!t || t.on !== on || (t.once && fired().includes(i))) return false;
+        if (on === 'flag' && (t.flag != null && String(t.flag).replace(/^world\./i, '') !== data.name)) return false;
+        if (on === 'flag' && 'to' in t && String(applyValue(undefined, t.to)) !== String(data.value)) return false;
+        if (on === 'given' && ((t.who && String(t.who).toLowerCase() !== String(data.who).toLowerCase()) || (t.item && !itemMatches(data.item, t.item)))) return false;
+        return check(t.if, host.scope(t.as || data.who || null, {}));
+      });
+      if (!hits.length) return;
+      busy = true;
+      try {
+        for (const [t, i] of hits) {
+          if (t.once) fired().push(i);
+          host.log?.(`trigger ${on}${t.flag ? ' ' + t.flag : ''}${t.as ? ' as ' + t.as : ''}`);
+          const me = t.as || data.who || null;
+          const r = await perform(t.do, { host, state, me, vars: {}, runner, triggers: null });
+          if (r.started && me) await runner?.advance(me, { until: 'wait' });
+        }
+      } finally { busy = false; }
+    },
+  };
+  state.on(({ name, value }) => { api.fire('flag', { name, value }); });
+  return api;
+}

package/validate.js

@@ -0,0 +1,91 @@
+// validate(scenario) -> [{ level: 'error' | 'warning', where, message }]
+// Checks the scripted parts of a scenario before anyone plays it (the world
+// generator writes these, so mistakes are likely):
+//   conditions that do not parse; goto/then/else/exit/other/closed/options
+//   targets that do not exist; steps nothing reaches; menus and workflows named
+//   but missing; flags read but never set nor given a starting value; a
+//   "choose" with no default, or a flow menu step with no "other", in a world
+//   with no model ("brain": "none"); triggers with an unknown "on".
+import { parse, ExprError } from './expr.js';
+
+const TRIGGER_ON = ['flag', 'given', 'start'];
+export function validate(scn = {}) {
+  const out = [], err = (where, message) => out.push({ level: 'error', where, message }), warn = (where, message) => out.push({ level: 'warning', where, message });
+  const menus = scn.menus || {}, flows = scn.workflows || {}, noModel = scn.brain === 'none';
+  const read = new Map(), set = new Set(Object.keys(scn.flags || {}));
+  const flagsIn = (text, where) => { for (const m of String(text ?? '').matchAll(/world\.([\w-]+)/gi)) if (!read.has(m[1])) read.set(m[1], where); };
+  const cond = (text, where) => {
+    if (text == null || typeof text === 'boolean') return;
+    for (const t of [].concat(text)) { try { parse(t); } catch (e) { err(where, e instanceof ExprError ? e.message : String(e)); } flagsIn(t, where); }
+  };
+  const sets = obj => { for (const k of Object.keys(obj || {})) set.add(k.replace(/^world\./i, '')); };
+  const actions = (a, where) => {
+    if (!a) return;
+    sets(a.set);
+    for (const t of [a.reply, a.say, ...[].concat(a.act ?? [])]) flagsIn(t, where);
+    const st = typeof a.start === 'string' ? a.start : a.start?.name;
+    if (st && !flows[st]) err(where, `workflow "${st}" does not exist`);
+    if (a.workflow && !flows[a.workflow]) err(where, `workflow "${a.workflow}" does not exist`);
+  };
+  const menuRef = (ref, where) => { if (typeof ref === 'string' && !menus[ref]) err(where, `menu "${ref}" does not exist`); };
+
+  // menus a workflow opens: the workflow acts on the choice, the items need no actions
+  const flowMenus = new Set(Object.values(flows).flatMap(f => (f?.steps || []).map(s => s?.menu).filter(x => typeof x === 'string')));
+  for (const [id, m] of Object.entries(menus)) {
+    if (!Array.isArray(m?.items) || !m.items.length) { err(`menus.${id}`, 'a menu needs items'); continue; }
+    m.items.forEach((it, n) => {
+      const where = `menus.${id}.items[${it?.id || n}]`;
+      cond(it?.if, where); actions(it, where); menuRef(it?.menu, where);
+      if (noModel && it && !flowMenus.has(id) && !it.menu && !it.do && it.reply == null && it.act == null && it.set == null && it.take == null && it.give == null && !it.workflow && !it.start && !it.stop && !/^(bye|leave|close|exit|goodbye)$/i.test(it.id || ''))
+        warn(where, 'nothing happens in a world with no model: give it a reply or act');
+    });
+  }
+  for (const a of scn.agents || []) {
+    const where = `agents.${a?.id}`;
+    if (Array.isArray(a?.menu)) a.menu.forEach(e => { cond(e?.if, where + '.menu'); menuRef(e?.menu, where + '.menu'); });
+    else menuRef(a?.menu, where + '.menu');
+    if (a?.workflow && !flows[a.workflow]) err(where, `workflow "${a.workflow}" does not exist`);
+  }
+  for (const [name, f] of Object.entries(flows)) {
+    const steps = f?.steps; if (!Array.isArray(steps) || !steps.length) { err(`workflows.${name}`, 'a workflow needs steps'); continue; }
+    const ids = new Map(steps.map((s, i) => [s?.id ?? '#' + i, i]));
+    const at = ref => ref == null ? -1 : typeof ref === 'number' ? ref : ids.has(ref) ? ids.get(ref) : -2;
+    const targets = (s, i) => {
+      const t = [];
+      for (const k of ['goto', 'then', 'else', 'exit', 'other', 'closed']) if (s[k] != null) t.push([k, s[k]]);
+      for (const [o, ref] of Object.entries(s.options || {})) t.push([`options.${o}`, ref]);
+      return t;
+    };
+    const reach = new Set(), todo = [f.start != null ? at(f.start) : 0];
+    while (todo.length) {
+      const i = todo.pop(); if (i < 0 || i >= steps.length || reach.has(i)) continue; reach.add(i);
+      const s = steps[i] || {};
+      const branches = targets(s, i).map(([, r]) => at(r)).filter(x => x >= 0);
+      todo.push(...branches);
+      const falls = !s.end && s.goto == null && !(s.if != null && s.then != null && s.else != null) && !(s.choose != null && s.options);
+      if (falls) todo.push(i + 1);
+    }
+    steps.forEach((s, i) => {
+      const where = `workflows.${name}.steps[${s?.id || i}]`;
+      if (!s || typeof s !== 'object') { err(where, 'a step must be an object'); return; }
+      for (const [k, ref] of targets(s, i)) if (at(ref) === -2) err(where, `${k} goes to "${ref}", which is not a step`);
+      cond(s.if, where); sets(Object.fromEntries(Object.entries(s.set || {}).filter(([k]) => /^world\./i.test(k))));
+      for (const t of [s.command, s.prompt, s.choose]) flagsIn(t, where);
+      actions(s.do, where); menuRef(s.menu, where);
+      if (noModel && s.choose != null && s.default == null) warn(where, 'choose has no "default", and this world has no model to answer it');
+      if (noModel && s.prompt != null) warn(where, 'prompt needs a model, and this world has none');
+      if (s.menu != null && noModel && s.other == null) warn(where, 'words that fit no choice make this menu ask again: add "other" to branch on them');
+      if (!reach.has(i)) warn(where, 'nothing leads to this step');
+    });
+  }
+  for (const [i, t] of (scn.triggers || []).entries()) {
+    const where = `triggers[${i}]`;
+    if (!TRIGGER_ON.includes(t?.on)) err(where, `"on" must be one of ${TRIGGER_ON.join(', ')}`);
+    cond(t?.if, where); actions(t?.do, where);
+    if (t?.on === 'flag' && t.flag) flagsIn('world.' + String(t.flag).replace(/^world\./i, ''), where);
+  }
+  if (typeof scn.goal?.win?.if === 'string') cond(scn.goal.win.if, 'goal.win');
+  for (const [f, where] of read) if (!set.has(f)) warn(where, `flag "${f}" is read but never set and has no starting value in "flags"`);
+  for (const k of Object.keys(scn.facts || {})) if (!set.has(k)) warn(`facts.${k}`, `flag "${k}" is never set, so this fact never shows`);
+  return out;
+}