@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/core/page/fns.js

@@ -0,0 +1,539 @@
+/**
+ * Pages written with functions (76): what `context.page.ts` is written with. Every node and every action
+ * is a platform function returning its own type: `page()`, `block()`, `list()`, `field()`, `text()`,
+ * `data()`, `button()`, `doNow()`, `toolbox()`; actions `run()`, `createRow()`, `warmTransfer()`, …
+ * A node carries a mark no JSON can carry (31 §8), so data from outside never becomes a field or a
+ * button. The page module turns the tree into the envelope (`toFnPageResult`), the one thing the
+ * platform reads (`render.ts`): what the AI reads of the page does not change (76 §2.20).
+ *
+ * The types here are the generic ones; `typed.ts` binds `page`'s extraction, `field`'s slot, `createRow`,
+ * `deleteRow` and `run` to one sequence's tables, functions (`fn`) and page actions (`act`) (`__gen/index.ts`).
+ *
+ * Runs in the page's QuickJS sandbox like the rest of the page module: no imports at runtime but the
+ * page module's own.
+ */
+import { announceAction, cancelFollowUpAction, createRowAction, deleteRowAction, endAction, fieldCell, followUpAction, isChoose, keypadAction, refFieldCell, runFunction, transferTo, voicemailAction, } from './define.js';
+// ---------------------------------------------------------------------------------------------
+// Marks
+/** The mark of a node: `Symbol.for`, the same in every copy of the page module a bundle may hold. */
+export const NODE = Symbol.for('superpanel.page.node');
+/** The mark of an action (what a button or `doNow` does). */
+export const ACTION = Symbol.for('superpanel.page.action');
+/** The mark of a handle `run()` takes: a company function (`fn.x`) or a page action (`act.x`). */
+export const HANDLE = Symbol.for('superpanel.page.handle');
+/** The mark of a platform tool (`pressKeypad()`, `convertTime()`). */
+export const TOOL = Symbol.for('superpanel.page.tool');
+const KINDS = new Set(['page', 'block', 'list', 'field', 'text', 'data', 'button', 'toolbox', 'do']);
+/** Whether `value` is a node a platform function made. */
+export function isNode(value) {
+    return typeof value === 'object' && value !== null && KINDS.has(value[NODE]);
+}
+function isAction(value) {
+    return typeof value === 'object' && value !== null && typeof value[ACTION] === 'string';
+}
+const node = (value) => value;
+// ---------------------------------------------------------------------------------------------
+// Nodes
+/** The page (76 §2.7): settings, then content. What a page function returns, unless it returns `doNow()`. */
+export function page(settings, content) {
+    settingsOf('page', settings, ['title', 'description', 'guide', 'extraction', 'voice']);
+    contentOf('page', content);
+    return node({ [NODE]: 'page', settings, content });
+}
+/** A block (76 §2.7): settings (`{}` for none), then its content by name. */
+export function block(settings, content) {
+    settingsOf('block', settings, ['title', 'description']);
+    contentOf('block', content);
+    return node({ [NODE]: 'block', settings, content });
+}
+/** A list (76 §2.10): settings, then items, all one kind of node (`rows.map((r) => block({}, { … }))`). */
+export function list(settings, items) {
+    settingsOf('list', settings, ['title', 'description']);
+    if (!Array.isArray(items))
+        throw new Error('list(settings, items): items is an array of nodes, all one kind (rows.map((r) => block({}, { … })))');
+    return node({ [NODE]: 'list', settings, items });
+}
+/** A field the AI may write, or read only (`readOnly`). A ref field is `refField()`. */
+export function field(slot, options = {}) {
+    checkOptions('field()', options, ['readOnly', 'expand']);
+    const cell = fieldCell(slot, options);
+    return node({ [NODE]: 'field', make: () => cell });
+}
+/** A ref field: writable, the rows it may be set to (`options`); read-only, who its value is (`label`). */
+export function refField(slot, options) {
+    checkOptions('refField()', options, ['options', 'readOnly', 'label']);
+    const given = options;
+    if (given.readOnly && given.options !== undefined)
+        throw new Error('refField(): read-only, it says who the current value is with label, not options');
+    if (!given.readOnly && given.label !== undefined)
+        throw new Error('refField(): label is for a read-only ref field; a writable one offers options');
+    const readOnly = given.readOnly === true;
+    const listed = readOnly && typeof given.label === 'string' && typeof slot?.value === 'string' ? [{ id: slot.value, label: given.label }] : given.options;
+    const cell = refFieldCell(slot, { ...(listed ? { options: listed } : {}), ...(readOnly ? { readOnly: true } : {}) });
+    return node({ [NODE]: 'field', make: () => cell });
+}
+/** One text, read only. A value that may be empty: `x ? text(x) : undefined`. */
+export function text(value) {
+    if (typeof value === 'number')
+        value = String(value);
+    if (typeof value !== 'string') {
+        throw new Error(`text(): takes a string or a number, not ${describe(value)}${isNode(value) ? '' : ': data is data(…)'}`);
+    }
+    if (!value.trim())
+        throw new Error('text() is empty: leave it out when there is nothing to show (note ? text(note) : undefined)');
+    return node({ [NODE]: 'text', text: value });
+}
+/** Data shown as it is, whatever keys it has (`$action` too): never a field or a button (31 §4). */
+export function data(value) {
+    // `undefined` is nothing to show: the item is left out, as an `undefined` value of an object was.
+    return node({ [NODE]: 'data', value: value === undefined ? undefined : plain('data()', value) });
+}
+/** What the AI can press (31 §5): its words, and what it does (`action`). */
+export function button(options) {
+    const given = options;
+    checkOptions('button()', given, ['action', 'title', 'does']);
+    if (!isAction(given.action))
+        throw new Error(`button(): action is what it does, an action function's result (run(…), createRow(…), warmTransfer(…), …), not ${describe(given.action)}`);
+    const verb = given.action[ACTION];
+    if (verb === 'announce')
+        throw new Error('button(): announce() is only for doNow(): the AI never presses it');
+    for (const key of ['title', 'does']) {
+        if (given[key] !== undefined && typeof given[key] !== 'string')
+            throw new Error(`button(): ${key} is text`);
+    }
+    // What the AI needs to tell buttons apart (30 §7.4): a function or a page action says what it is and
+    // when to press it (its name is the code's); a transfer who it goes to (the AI sees no number).
+    if (verb === 'run' && (!given.title || !given.does))
+        throw new Error('button(): a run() button needs title and does: what it is and when to press it');
+    if (verb === 'transfer' && !given.title)
+        throw new Error('button(): a transfer needs a title: the AI sees no number, the title is who it goes to');
+    const words = { ...(given.title ? { label: given.title } : {}), ...(given.does ? { description: given.does } : {}) };
+    return node({ [NODE]: 'button', action: given.action, words });
+}
+/**
+ * What the page does now (31 §6), instead of a page: the AI neither sees nor presses it. The action has
+ * its run key, the name `tried(ctx.runs, …)` checks (76 §2.14); `wait: false` only for `run()`: an action
+ * that may be one of several (`flag ? run(…) : end()`) only when every one is a `run()`.
+ */
+export function doNow(action, options = {}) {
+    if (!isAction(action))
+        throw new Error(`doNow(): takes an action (run(…), keypad(…), announce(…), …), not ${describe(action)}`);
+    checkOptions('doNow()', options, ['wait']);
+    const verb = action[ACTION];
+    if (verb === 'scheduleFollowUp' || verb === 'cancelFollowUp')
+        throw new Error(`doNow(): ${verb}() is a button: the AI books it with the customer`);
+    if (!action.runKey)
+        throw new Error(`doNow(${verb}()): give the action a runKey, the name tried(ctx.runs, …) checks (76 §2.14)`);
+    const wait = options.wait;
+    if (wait !== undefined) {
+        if (typeof wait !== 'boolean')
+            throw new Error('doNow(): wait is true or false');
+        if (verb !== 'run' && wait === false)
+            throw new Error(`doNow(${verb}()): only run() may go on in the background (wait: false)`);
+    }
+    return node({ [NODE]: 'do', action, ...(wait !== undefined ? { wait } : {}) });
+}
+/** The platform's tools the AI may use on this page (76 §2.18): one toolbox a page, each tool once. */
+export function toolbox(tools) {
+    if (!Array.isArray(tools))
+        throw new Error('toolbox([...]): a list of tools (pressKeypad(), convertTime())');
+    const names = tools.map((tool) => {
+        const name = typeof tool === 'object' && tool !== null ? tool[TOOL] : undefined;
+        if (typeof name !== 'string')
+            throw new Error(`toolbox(): ${describe(tool)} is not a tool: pressKeypad(), convertTime()`);
+        return name;
+    });
+    const twice = names.find((name, i) => names.indexOf(name) !== i);
+    if (twice)
+        throw new Error(`toolbox(): ${twice}() is in it twice`);
+    return node({ [NODE]: 'toolbox', tools: names });
+}
+/** Press keys on the other side's automated phone menu (76 §2.18): a call only. */
+export function pressKeypad() {
+    return { [TOOL]: 'pressKeypad' };
+}
+/** Convert between a local time in a time zone and an instant, UTC (76 §2.18, §2.19). */
+export function convertTime() {
+    return { [TOOL]: 'convertTime' };
+}
+// ---------------------------------------------------------------------------------------------
+// Actions
+const action = (verb, runKey, build) => ({ [ACTION]: verb, build, ...(runKey !== undefined ? { runKey } : {}) });
+const keyed = (built, runKey) => {
+    // The run key is the action's own (30 §7.3): the same whoever runs it, the page or the AI.
+    if (runKey)
+        built.key = runKey;
+    return { action: built, ...(runKey ? { key: runKey } : {}) };
+};
+function checkRunKey(at, runKey) {
+    if (runKey === undefined)
+        return undefined;
+    if (typeof runKey !== 'string' || !runKey.trim())
+        throw new Error(`${at}: runKey is a name (text)`);
+    if (runKey === '__proto__')
+        throw new Error(`${at}: runKey __proto__: pick another name (JavaScript keeps it for an object's prototype)`);
+    return runKey;
+}
+/**
+ * What the page fixed (`prefill`) and the rows the AI chooses among (`options`, 35 §2), as one map the
+ * platform tells apart: a `choose(...)` is the AI's choice, anything else is fixed.
+ */
+function givenRows(at, options, mode) {
+    const prefill = (options.prefill ?? {});
+    if (typeof prefill !== 'object' || Array.isArray(prefill))
+        throw new Error(`${at}: prefill is an object, parameter → value`);
+    for (const [key, value] of Object.entries(prefill)) {
+        if (isChoose(value))
+            throw new Error(`${at}: prefill is what the page fixed: the rows the AI chooses ${key} among go in options: { ${key}: choose(...) }`);
+    }
+    if (options.options === undefined)
+        return { ...prefill };
+    if (mode === 'do')
+        throw new Error(`${at}: in doNow() nobody chooses: no options, prefill every parameter`);
+    const chosen = options.options;
+    for (const [key, value] of Object.entries(chosen)) {
+        if (!isChoose(value))
+            throw new Error(`${at}: options.${key} is choose(rows, label): the rows the AI chooses among, each with what it sees of it`);
+        if (key in prefill)
+            throw new Error(`${at}: ${key} is both prefilled and in options: fix it, or let the AI choose`);
+    }
+    return { ...chosen, ...prefill };
+}
+export function run(handle, options = {}) {
+    const kind = typeof handle === 'object' && handle !== null ? handle[HANDLE] : undefined;
+    const name = handle?.name;
+    if ((kind !== 'function' && kind !== 'action') || typeof name !== 'string') {
+        throw new Error(typeof handle === 'function'
+            ? `run(${handle.name || '…'}): a plain function is not a page action: put it in actions.ts (export const actions = { name: async (ctx: ActionCtx, args) => … }) and run(act.name) (76 §2.11)`
+            : `run(): takes fn.<name> (a company function) or act.<name> (a page action), not ${describe(handle)}`);
+    }
+    const at = `run(${kind === 'function' ? 'fn' : 'act'}.${name})`;
+    checkOptions(at, options, ['prefill', 'options', 'args', 'say', 'runKey']);
+    const runKey = checkRunKey(at, options.runKey);
+    if (kind === 'action' && options.say !== undefined)
+        throw new Error(`${at}: say is for a company function: a page action runs at once`);
+    return action('run', runKey, (words, mode) => {
+        if (mode === 'do' && options.args !== undefined)
+            throw new Error(`${at}: in doNow() the AI fills nothing: no args`);
+        const prefill = givenRows(at, options, mode);
+        const args = options.args === undefined ? undefined : plain(`${at} args`, options.args);
+        if (kind === 'function') {
+            const built = runFunction(name, { ...words, ...(options.say !== undefined ? { say: options.say } : {}) });
+            if (Object.keys(prefill).length)
+                built.prefill = prefill;
+            if (args)
+                built.args = args;
+            return keyed(built, runKey);
+        }
+        const built = { $action: 'custom', name, prefill: Object.fromEntries(Object.entries(prefill).filter(([, value]) => value !== undefined)) };
+        if (words.label)
+            built.label = words.label;
+        if (words.description)
+            built.description = words.description;
+        if (args)
+            built.args = args;
+        return keyed(built, runKey);
+    });
+}
+/** Add a row (15 §10.6): `fields` are what the AI fills, `prefill` what the page fixed, `options` a ref field's rows. */
+export function createRow(table, options) {
+    const at = `createRow('${table}')`;
+    if (typeof table !== 'string' || !table)
+        throw new Error('createRow(table, …): the table is its name');
+    checkOptions(at, options, ['fields', 'required', 'prefill', 'options', 'runKey']);
+    if (!Array.isArray(options.fields))
+        throw new Error(`${at}: fields is a list of the fields the AI fills`);
+    const runKey = checkRunKey(at, options.runKey);
+    return action('createRow', runKey, (words, mode) => keyed(createRowAction(table, { fields: options.fields, ...(options.required ? { required: options.required } : {}), ...words })(givenRows(at, options, mode)), runKey));
+}
+/** Delete a row and everything under it (15 §10.6.1). */
+export function deleteRow(row, options = {}) {
+    checkOptions('deleteRow()', options, ['reason', 'runKey']);
+    const runKey = checkRunKey('deleteRow()', options.runKey);
+    const reason = options.reason;
+    // Checked now: a row that is not one fails where it is written.
+    deleteRowAction(row);
+    return action('deleteRow', runKey, (words) => keyed(deleteRowAction(row, { ...words, ...(reason !== undefined ? { reason } : {}) }), runKey));
+}
+const TRANSFER_KEYS = ['to', 'briefing', 'language', 'sipAuth', 'callerId', 'runKey'];
+function transfer(mode, fnName, options, extra) {
+    const at = `${fnName}()`;
+    if (typeof options !== 'object' || options === null)
+        throw new Error(`${at}: takes { to, … }`);
+    checkOptions(at, options, [...TRANSFER_KEYS, ...extra]);
+    if (typeof options.to !== 'string' || !options.to.trim())
+        throw new Error(`${at}: to is the number or SIP URI to call`);
+    if (options.whisper !== undefined && (typeof options.whisper !== 'string' || !options.whisper.trim()))
+        throw new Error(`${at}: whisper is text: who it is and what about`);
+    const runKey = checkRunKey(at, options.runKey);
+    const spec = { ...pickDefined(options, ['sipAuth', 'callerId', 'briefing', 'bridge', 'language', 'whisper']), to: options.to, mode };
+    transferTo(spec);
+    return action('transfer', runKey, (words) => keyed(transferTo({ ...spec, ...words }), runKey));
+}
+/** Put the customer through; the person hears the briefing first and does not confirm (76 §2.9). */
+export function coldTransfer(options) {
+    return transfer('cold', 'coldTransfer', options, []);
+}
+/** The customer waits; the person confirms, hears the briefing, then is put through (76 §2.9). */
+export function warmTransfer(options) {
+    return transfer('warm', 'warmTransfer', options, ['whisper']);
+}
+/** The AI keeps talking with the customer while the person is called; put through once they take it (76 §2.9). */
+export function backgroundTransfer(options) {
+    return transfer('background', 'backgroundTransfer', options, ['whisper', 'bridge']);
+}
+/** End the conversation (a call hangs up once the last line has played). */
+export function end(options = {}) {
+    checkOptions('end()', options, ['runKey']);
+    const runKey = checkRunKey('end()', options.runKey);
+    return action('end', runKey, (words) => keyed(endAction(words), runKey));
+}
+/** Leave a message on the voicemail, word for word, then hang up (25 §13). */
+export function voicemail(options) {
+    checkOptions('voicemail()', options, ['text', 'runKey']);
+    const runKey = checkRunKey('voicemail()', options.runKey);
+    voicemailAction(options.text);
+    return action('voicemail', runKey, (words) => keyed(voicemailAction(options.text, words), runKey));
+}
+/** Ask the customer to press a key; what they press is written to `write` (through `map`). */
+export function keypad(options) {
+    checkOptions('keypad()', options, ['runKey', 'say', 'digits', 'timeoutMs', 'write', 'map']);
+    const runKey = checkRunKey('keypad()', options.runKey);
+    if (!runKey)
+        throw new Error('keypad(): runKey is required, the name tried(ctx.runs, …) checks');
+    const spec = pickDefined(options, ['say', 'digits', 'timeoutMs', 'write', 'map']);
+    keypadAction(runKey, spec);
+    return action('keypad', runKey, (words) => ({ action: keypadAction(runKey, { ...spec, ...words }), key: runKey }));
+}
+/** Book the case's next step (40 §2.2), or move one already booked (51 §2). The AI gives when, in UTC (76 §2.19). */
+export function scheduleFollowUp(options) {
+    checkOptions('scheduleFollowUp()', options, ['channels', 'prefill', 'options', 'runKey']);
+    const runKey = checkRunKey('scheduleFollowUp()', options.runKey);
+    return action('scheduleFollowUp', runKey, (words) => {
+        const prefill = givenRows('scheduleFollowUp()', options, 'button');
+        return keyed(followUpAction({ channels: options.channels, ...(runKey ? { key: runKey } : {}), ...words, ...(Object.keys(prefill).length ? { prefill } : {}) }), runKey);
+    });
+}
+/** Cancel the case's next step (40 §2.2): the AI says why. */
+export function cancelFollowUp(options = {}) {
+    checkOptions('cancelFollowUp()', options, ['runKey']);
+    const runKey = checkRunKey('cancelFollowUp()', options.runKey);
+    return action('cancelFollowUp', runKey, (words) => keyed(cancelFollowUpAction({ ...(runKey ? { key: runKey } : {}), ...words }), runKey));
+}
+/** Say a fixed text, word for word (a compliance statement): `doNow()` only. `answers`: it answers what the customer said. */
+export function announce(options) {
+    checkOptions('announce()', options, ['runKey', 'text', 'answers']);
+    const runKey = checkRunKey('announce()', options.runKey);
+    if (!runKey)
+        throw new Error('announce(): runKey is required, the name tried(ctx.runs, …) checks');
+    announceAction(runKey, options.text);
+    return action('announce', runKey, () => ({ action: announceAction(runKey, options.text, { answers: options.answers === true }), key: runKey }));
+}
+// ---------------------------------------------------------------------------------------------
+// Page actions (76 §2.11) and company functions (§2.15)
+/** `fn` of `__gen` (76 §2.15): a handle per company function, by name; the types say which names there are. */
+export function functionHandles() {
+    return new Proxy({}, {
+        get(_, name) {
+            if (typeof name !== 'string')
+                return undefined;
+            return { [HANDLE]: 'function', name };
+        },
+    });
+}
+/** `act` of `__gen` (76 §2.11): a handle per page action of `actions.ts`, by name; the types say which names there are. */
+export function actionHandles() {
+    return new Proxy({}, {
+        get(_, name) {
+            if (typeof name !== 'string')
+                return undefined;
+            return { [HANDLE]: 'action', name };
+        },
+    });
+}
+// ---------------------------------------------------------------------------------------------
+// The envelope: what crosses out of the sandbox (31 §8)
+/** What a page function returned, as the platform reads it: `page()` or `doNow()`, as its envelope. */
+export function toFnPageResult(value) {
+    if (!isNode(value) || (value[NODE] !== 'page' && value[NODE] !== 'do')) {
+        throw new Error(`a page function returns page(…) or doNow(…), not ${isNode(value) ? `${value[NODE]}()` : describe(value)} (76 §2.1)`);
+    }
+    if (value[NODE] === 'do') {
+        const built = value.action.build({}, 'do');
+        return { $envelope: 1, do: { action: built.action, ...(built.key ? { key: built.key } : {}), ...(value.wait !== undefined ? { wait: value.wait } : {}) } };
+    }
+    const settings = value.settings;
+    const out = { children: [] };
+    for (const key of ['title', 'description', 'guide']) {
+        if (settings[key] !== undefined && settings[key] !== null)
+            out[key] = settings[key];
+    }
+    if (settings.extraction !== undefined)
+        out.extraction = plain('page() extraction', settings.extraction);
+    if (settings.voice !== undefined)
+        out.voice = plain('page() voice', settings.voice);
+    const toolboxes = { count: 0 };
+    out.children = contentNodes('page', value.content, 1, toolboxes);
+    return { $envelope: 1, page: out };
+}
+const MAX_DEPTH = 32;
+/** A block's or the page's content: each entry a node, named by its key; a skipped one left out. */
+function contentNodes(where, content, depth, toolboxes) {
+    if (depth > MAX_DEPTH)
+        throw new Error(`${where}: nested deeper than ${MAX_DEPTH}`);
+    const nodes = [];
+    for (const [key, value] of Object.entries(content)) {
+        const out = itemNode(`${where}.${key}`, key, value, depth, toolboxes);
+        if (out)
+            nodes.push(out);
+    }
+    return nodes;
+}
+function itemNode(where, key, value, depth, toolboxes) {
+    if (value === undefined || value === null || value === false)
+        return null;
+    if (!isNode(value))
+        throw new Error(notANode(where, value));
+    switch (value[NODE]) {
+        case 'page':
+            throw new Error(`${where}: page() is the whole page, never inside a block`);
+        case 'do':
+            throw new Error(`${where}: doNow() is what a page function returns instead of a page, never on it`);
+        case 'block': {
+            const out = { k: 'block', key, list: false, children: contentNodes(where, value.content, depth + 1, toolboxes) };
+            wordsOf(out, value.settings);
+            return out;
+        }
+        case 'list': {
+            const items = value.items.filter((item) => item !== undefined && item !== null && item !== false);
+            const kinds = new Set(items.map((item) => (isNode(item) ? item[NODE] : describe(item))));
+            if (kinds.size > 1)
+                throw new Error(`${where}: list items are all one kind: all block(), all field(), all text() or all button() (it has ${[...kinds].join(', ')})`);
+            const kind = [...kinds][0];
+            if (kind !== undefined && !['block', 'field', 'text', 'button'].includes(kind)) {
+                throw new Error(`${where}: a list holds block(), field(), text() or button(), not ${isNode(items[0]) ? `${kind}()` : kind}`);
+            }
+            const children = items.map((item, i) => itemNode(`${where}.${i}`, String(i), item, depth + 1, toolboxes)).filter((n) => n !== null);
+            const out = { k: 'block', key, list: true, children };
+            wordsOf(out, value.settings);
+            return out;
+        }
+        case 'field':
+            return { k: 'field', key, cell: value.make() };
+        case 'text':
+            return { k: 'data', key, value: value.text };
+        case 'data':
+            return value.value === undefined ? null : { k: 'data', key, value: value.value };
+        case 'button':
+            // The platform gives a button its id, from what it does and on which rows (46 §2.1): its key is the code's.
+            return { k: 'button', key: '', action: value.action.build(value.words, 'button').action };
+        case 'toolbox':
+            if (++toolboxes.count > 1)
+                throw new Error(`${where}: a page has one toolbox()`);
+            return { k: 'toolbox', key, tools: [...value.tools] };
+    }
+}
+function wordsOf(out, settings) {
+    if (out.k !== 'block')
+        return;
+    if (typeof settings.title === 'string')
+        out.title = settings.title;
+    if (typeof settings.description === 'string')
+        out.description = settings.description;
+}
+function notANode(where, value) {
+    if (typeof value === 'string' || typeof value === 'number') {
+        return `${where}: ${describe(value)} is not a node: a text is text(…), data is data(…); a value that may be empty is x ? text(x) : undefined, not x && text(x)`;
+    }
+    if (typeof value === 'function')
+        return `${where}: a function is not page content (a button is button({ … }))`;
+    if (isAction(value))
+        return `${where}: an action is placed with button({ title, does, action }) or doNow(action)`;
+    if (isSlotLike(value))
+        return `${where}: a slot is placed with field(slot) (read only: field(slot, { readOnly: true }))`;
+    return `${where}: ${describe(value)} is not a node: data is data(…), a group of nodes block({}, { … })`;
+}
+// ---------------------------------------------------------------------------------------------
+function settingsOf(at, settings, allowed) {
+    if (typeof settings !== 'object' || settings === null || Array.isArray(settings) || isNode(settings)) {
+        throw new Error(`${at}(settings, content): settings come first, an object (${at}({}, { … }) when there are none)`);
+    }
+    checkOptions(`${at}() settings`, settings, allowed);
+    for (const key of ['title', 'description', 'guide']) {
+        const value = settings[key];
+        if (value !== undefined && typeof value !== 'string')
+            throw new Error(`${at}() ${key}: must be text`);
+    }
+}
+function contentOf(at, content) {
+    if (typeof content !== 'object' || content === null || Array.isArray(content) || isNode(content)) {
+        throw new Error(`${at}(settings, content): content is an object, its items by name (${at}({}, { name: field(…) }))`);
+    }
+}
+/** An option a function does not take is an error (31 §4): a misspelt one would otherwise do nothing, silently. */
+function checkOptions(at, options, allowed) {
+    if (options === undefined)
+        return;
+    if (typeof options !== 'object' || options === null || Array.isArray(options))
+        throw new Error(`${at}: takes an object`);
+    const unknown = Object.keys(options).filter((key) => !allowed.includes(key) && options[key] !== undefined);
+    if (unknown.length)
+        throw new Error(`${at}: has no ${unknown.join(', ')} (it takes ${allowed.join(', ')})`);
+}
+function pickDefined(props, keys) {
+    const out = {};
+    for (const key of keys)
+        if (props[key] !== undefined)
+            out[key] = props[key];
+    return out;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) && !isNode(value);
+}
+function isSlotLike(value) {
+    if (!isPlainObject(value) || !isPlainObject(value.ref) || !('state' in value))
+        return false;
+    const ref = value.ref;
+    return typeof ref.table === 'string' && typeof ref.id === 'string' && typeof ref.field === 'string';
+}
+function describe(value) {
+    if (Array.isArray(value))
+        return 'a list';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return `a string ${JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}…` : value)}`;
+    return typeof value === 'object' ? 'an object' : `a ${typeof value}`;
+}
+/** Data as JSON keeps it: no functions, no slots, no nodes, `undefined` left out. */
+function plain(where, value, depth = 0) {
+    if (depth > MAX_DEPTH)
+        throw new Error(`${where}: nested deeper than ${MAX_DEPTH}`);
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : String(value);
+    if (typeof value === 'function')
+        throw new Error(`${where}: a function is not data`);
+    if (isNode(value))
+        throw new Error(`${where}: data() holds data only: put page nodes in block() (found ${value[NODE]}())`);
+    if (isAction(value))
+        throw new Error(`${where}: data() holds data only: an action goes in button() or doNow()`);
+    if (isSlotLike(value))
+        throw new Error(`${where}: a slot is placed with field(slot) (read only: field(slot, { readOnly: true }))`);
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map((item, i) => plain(`${where}.${i}`, item, depth + 1));
+    if (typeof value === 'object') {
+        const out = {};
+        for (const [key, item] of Object.entries(value)) {
+            if (item === undefined)
+                continue;
+            out[key] = plain(`${where}.${key}`, item, depth + 1);
+        }
+        return out;
+    }
+    return String(value);
+}
+//# sourceMappingURL=fns.js.map

package/dist/core/page/memory-reader.d.ts

@@ -0,0 +1,27 @@
+import type { CompiledSlotSchema } from '../slot/types.js';
+import { type RecordsCall, type RowOut, type SlotOut } from './records-query.js';
+import type { HostResult } from './sandbox.js';
+/**
+ * A test's rows, by table: each an `id` and its fields' values (a missing or null field is empty). A field
+ * asked and not known, declined, or with a reason is `{ $slot: { value, state, reason } }` (a turn's
+ * export writes them so, 68 §7.4).
+ */
+export type MemoryRows = Readonly<Record<string, ReadonlyArray<Readonly<Record<string, unknown>>>>>;
+export type MemoryReader = {
+    execute(calls: RecordsCall[]): Promise<HostResult[]>;
+    row(table: string, id: string): RowOut | null;
+    rowInfo(id: string): {
+        table: string;
+        slots: Record<string, Omit<SlotOut, 'ref' | 'row'>>;
+    } | undefined;
+    parentsOf(table: string): string[];
+    adoptRow(table: string, row: RowOut): void;
+    /** Every read, in order: `table.method` and its arguments, for a test that checks what the page read. */
+    readonly calls: RecordsCall[];
+};
+export declare function createMemoryReader(input: {
+    schema: CompiledSlotSchema;
+    rows: MemoryRows;
+    now: number;
+}): MemoryReader;
+//# sourceMappingURL=memory-reader.d.ts.map