@superpanel-sdk/runtime 0.2.3 → 0.5.0

package/dist/core/page/render.js

@@ -0,0 +1,840 @@
+/**
+ * Page document → `RenderedPage` (15 §10.9 output). Runs on the platform, after the page script
+ * returned its document from the sandbox.
+ *
+ * The document is walked once. Every slot becomes a cell joined with its schema definition; its value
+ * is taken from what the platform itself read (`PageReads`), never from the document, and a slot
+ * whose row this run did not read is shown as plain read-only content (anti-forgery). Every action
+ * becomes a button with the function-call arguments the AI fills; what the page prefilled stays here,
+ * on the server. An action that cannot be pressed is left off the page.
+ *
+ * The rows on the page are the rows with a cell on it: a lookup cell, and an action's row parameter,
+ * choose among the rows of their table there (15 §10.15 point 9). So lookups and actions are rendered
+ * after the walk, once every row on the page is known.
+ *
+ * Cells are addressed by slot id `table#n.field` (`RowNames`: stable for a conversation, layout-free);
+ * actions and blocks by their page path (`injuries.rows.0.markError`), resolved against the very page
+ * the AI saw.
+ */
+import { parentOf } from '../slot/company-metadata.js';
+import { ROW_ID_FIELD } from '../slot/schema.js';
+import { getCompiledTable, getTableField } from '../slot/compile-schema.js';
+import { isChoose } from './define.js';
+// ---------------------------------------------------------------------------------------------
+// Row names (15 §10.6.2)
+/**
+ * `table#n` for each row a conversation has seen: the same row keeps its name on every page of the
+ * conversation; names only grow and are never reused, so a late output naming a deleted row's name
+ * cannot reach another row. Serialisable (`toJSON` / `fromJSON`) so a session can keep it.
+ */
+export class RowNames {
+    byId = new Map();
+    byName = new Map();
+    counters = new Map();
+    name(table, id) {
+        const known = this.byId.get(id);
+        if (known)
+            return known;
+        const n = (this.counters.get(table) ?? 0) + 1;
+        this.counters.set(table, n);
+        const name = `${table}#${n}`;
+        this.byId.set(id, name);
+        this.byName.set(name, { table, id });
+        return name;
+    }
+    resolve(name) {
+        return this.byName.get(name);
+    }
+    nameOf(id) {
+        return this.byId.get(id);
+    }
+    toJSON() {
+        return [...this.byName.entries()].map(([name, { table, id }]) => [name, table, id]);
+    }
+    static fromJSON(entries) {
+        const names = new RowNames();
+        for (const [name, table, id] of entries) {
+            names.byId.set(id, name);
+            names.byName.set(name, { table, id });
+            const n = Number(name.slice(name.lastIndexOf('#') + 1));
+            if (n > (names.counters.get(table) ?? 0))
+                names.counters.set(table, n);
+        }
+        return names;
+    }
+}
+export class PageDocumentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PageDocumentError';
+    }
+}
+const MAX_DEPTH = 32;
+/** Channel actions only a call can do; by text only `end` (17b §9.8). */
+const CALL_ONLY = new Set(['transfer', 'keypad', 'announce', 'voicemail']);
+export function renderDocument(input) {
+    const perform = performOf(input.document);
+    if (perform?.action.$action === 'channel' && input.channel !== undefined && input.channel !== 'call' && CALL_ONLY.has(perform.action.channel)) {
+        throw new PageDocumentError(`the page function returned ${perform.action.channel}, which only a call can do (this is ${input.channel})`);
+    }
+    if (perform) {
+        // An action to run now: rendered as a button on a page of its own, so its rows are checked the same way.
+        const inner = renderDocument({ ...input, document: { action: perform.action } });
+        const action = inner.actions['action'];
+        if (!action)
+            throw new PageDocumentError(`the action the page function returned cannot run: ${inner.warnings.join('; ') || 'no row to run it on'}`);
+        return { ...inner, auto: { action, key: perform.key ?? actionKey(perform.action), wait: perform.wait ?? true } };
+    }
+    const { schema, reads, names } = input;
+    if (!isPlainObject(input.document))
+        throw new PageDocumentError('the page script must return an object');
+    const cells = {};
+    const actions = {};
+    const rows = {};
+    const warnings = [];
+    /** Rows with a cell on the page, by table (page names). */
+    const cellRows = new Map();
+    const pendingActions = [];
+    const extractions = pageExtractions(input.document, schema, warnings);
+    const rowName = (table, id) => {
+        const name = names.name(table, id);
+        if (!rows[name]) {
+            const parent = parentOf(getCompiledTable(schema, table));
+            const parentValue = parent ? reads.row(id)?.slots[parent.field]?.value : null;
+            rows[name] = { table, id, parentId: typeof parentValue === 'string' ? parentValue : null };
+        }
+        return name;
+    };
+    const rowsOnPage = (table) => [...(cellRows.get(table) ?? [])];
+    const cellOf = (key, path, value) => {
+        const refCell = isRefFieldCell(value) ? value : null;
+        const fieldCell = isFieldCell(value) ? value : refCell ? { $field: true, slot: refCell.slot, ...(refCell.readOnly ? { readOnly: true } : {}) } : null;
+        const slot = fieldCell ? fieldCell.slot : value;
+        if (!isSlotLike(slot))
+            return null;
+        const ref = slot.ref;
+        const read = reads.row(ref.id);
+        const table = getCompiledTable(schema, ref.table);
+        const def = table?.fields[ref.field];
+        if (!read || read.table !== ref.table || !def || !(ref.field in read.slots)) {
+            warnings.push(`${path}: a slot this run did not read (${ref.table}.${ref.field}); shown as read-only text`);
+            return { kind: 'text', key, path, value: displayable(slot.value) };
+        }
+        const truth = read.slots[ref.field];
+        const name = rowName(ref.table, ref.id);
+        const onPage = cellRows.get(ref.table) ?? new Set();
+        onPage.add(name);
+        cellRows.set(ref.table, onPage);
+        const slotId = `${name}.${ref.field}`;
+        const isParent = parentOf(table)?.field === ref.field;
+        const isLookup = Boolean(def.ref) && !isParent;
+        // A ref field is placed with refField: its candidates and their labels are the page's (26 §16.2 #7).
+        if (isLookup && fieldCell && !refCell)
+            throw new PageDocumentError(`${path}: ${ref.table}.${ref.field} is a ref field: place it with refField(slot, { options })`);
+        if (refCell && !isLookup)
+            throw new PageDocumentError(`${path}: refField(...) is for a ref field; ${ref.table}.${ref.field} is ${isParent ? 'the parent' : 'not a ref'}`);
+        const offered = refCell ? refOptions(path, refCell, def.ref.table) : null;
+        // The page decides (19-page-writable-cells): a slot placed as is is read-only, `field(...)` opens
+        // it. Never the row id or the parent. A lookup opens where its table's rows are on the page
+        // (settled below): the AI cannot make up a row id.
+        const fixed = isParent || ref.field === ROW_ID_FIELD;
+        if (fieldCell && !fieldCell.readOnly && fixed) {
+            warnings.push(`${path}: field(...) cannot open ${ref.table}.${ref.field} (${isParent ? 'the parent' : 'the row id'}); it stays read-only`);
+        }
+        // A ref field with no row to offer is shown, not opened: nothing to choose (data, not a page mistake).
+        const placeWritable = fieldCell !== null && !fieldCell.readOnly && !fixed && (!offered || offered.length > 0);
+        const existing = cells[slotId];
+        if (existing) {
+            existing.writable ||= placeWritable;
+            existing.paths.push(path);
+        }
+        else {
+            const cell = {
+                slotId,
+                ref: { table: ref.table, id: ref.id, field: ref.field },
+                row: name,
+                label: def.label,
+                type: def.dataType,
+                choices: def.options,
+                value: truth.value,
+                state: truth.state,
+                reason: truth.reason,
+                updatedAt: truth.updatedAt,
+                writable: placeWritable,
+                paths: [path],
+            };
+            if (def.description)
+                cell.description = def.description;
+            if (def.extraction)
+                cell.extraction = def.extraction;
+            if (isLookup)
+                cell.type = 'ref';
+            cells[slotId] = cell;
+        }
+        if (offered) {
+            const target = cells[slotId];
+            // Writable, the rows offered; read-only, only the labels (who the current value is).
+            if (placeWritable)
+                target.options = [...new Set([...(target.options ?? []), ...offered.map((o) => o.name)])];
+            target.optionLabels = { ...target.optionLabels, ...Object.fromEntries(offered.map((o) => [o.name, o.label])) };
+        }
+        const node = { kind: 'cell', key, path, slotId, readOnly: !placeWritable };
+        // A ref field's definition is always on the page: its meaning is not in its name (26 §16.2 #7).
+        if (fieldCell?.expand || refCell)
+            node.expand = true;
+        return node;
+    };
+    /** A refField's rows: each must be a row this run read, of the table the field points at (it goes on the page). */
+    const refOptions = (path, cell, target) => cell.options.map((option) => {
+        const read = reads.row(option.id);
+        if (!read || read.table !== target)
+            throw new PageDocumentError(`${path}: refField offers ${option.id}, not a ${target} row this run read`);
+        return { name: rowName(target, option.id), label: option.label };
+    });
+    const walk = (key, path, value, depth) => {
+        if (depth > MAX_DEPTH)
+            throw new PageDocumentError(`${path || 'page'}: nested deeper than ${MAX_DEPTH}`);
+        if (value === undefined || typeof value === 'function')
+            return null;
+        if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            return { kind: 'text', key, path, value };
+        }
+        if (isAction(value)) {
+            pendingActions.push({ path, value });
+            return { kind: 'action', key, path, actionId: path };
+        }
+        const cell = cellOf(key, path, value);
+        if (cell)
+            return cell;
+        if (Array.isArray(value)) {
+            const children = value
+                .map((item, i) => walk(String(i), join(path, String(i)), item, depth + 1))
+                .filter((n) => n !== null);
+            return { kind: 'block', key, path, list: true, children };
+        }
+        if (isPlainObject(value)) {
+            if (isRowLike(value)) {
+                warnings.push(`${path}: a whole row is not a cell; put its slots on the page`);
+            }
+            const block = { kind: 'block', key, path, list: false, children: [] };
+            if (typeof value.$title === 'string')
+                block.title = value.$title;
+            if (typeof value.$description === 'string')
+                block.description = value.$description;
+            pageMarks(block, value, path, depth === 0, warnings);
+            for (const [childKey, child] of Object.entries(value)) {
+                if (childKey.startsWith('$'))
+                    continue;
+                // A button's id is the keys joined with '.': a key with a '.' in it would collide with a nested one (26 §16.2 #3).
+                if (childKey.includes('.'))
+                    throw new PageDocumentError(`${join(path, childKey) || 'page'}: a key on the page cannot contain '.' (${JSON.stringify(childKey)})`);
+                const node = walk(childKey, join(path, childKey), child, depth + 1);
+                if (node)
+                    block.children.push(node);
+            }
+            return block;
+        }
+        return { kind: 'text', key, path, value: String(value) };
+    };
+    const root = walk('', '', input.document, 0);
+    // Every row on the page is known now: what lookups and row parameters may choose.
+    const env = { schema, reads, rowName, rowsOnPage, warnings, ...(input.channel ? { channel: input.channel } : {}) };
+    for (const { path, value } of pendingActions) {
+        const rendered = renderAction(path, value, env);
+        if (rendered)
+            actions[path] = rendered;
+    }
+    // An action that cannot be pressed is not on the page.
+    const prune = (block) => {
+        block.children = block.children.filter((child) => child.kind !== 'action' || child.actionId in actions);
+        for (const child of block.children)
+            if (child.kind === 'block')
+                prune(child);
+    };
+    prune(root);
+    const page = { root, cells, actions, rows, warnings };
+    if (extractions.size)
+        page.extractions = Object.fromEntries(extractions);
+    return page;
+}
+/**
+ * The action as the AI presses it, or null when it cannot be pressed on this page: with a warning when
+ * the page placed it wrong; silently when a required row choice has no row on the page (no injury yet
+ * to link a provider to), which is the data, not a mistake.
+ */
+function renderAction(path, action, env) {
+    const rendered = renderActionOf(path, action, env);
+    if (!rendered?.input)
+        return rendered;
+    const missing = unfillable(rendered.input.properties, rendered.input.required);
+    if (!missing)
+        return rendered;
+    // Said, so whoever reads the logs knows why the AI had no such button (25 §10).
+    env.warnings.push(`${path}: ${rendered.name} left off the page: no ${missing.table} row to choose for ${missing.key}`);
+    return null;
+}
+/** The first required row choice with no row to choose, at any depth; null when every one can be filled. */
+function unfillable(properties, required, prefix = '') {
+    for (const key of required ?? []) {
+        const prop = properties[key];
+        if (prop?.type === 'ref' && !prop.enum.length)
+            return { key: `${prefix}${key}`, table: prop.table };
+        if (prop?.type === 'object') {
+            const inner = unfillable(prop.properties, prop.required, `${prefix}${key}.`);
+            if (inner)
+                return inner;
+        }
+    }
+    return null;
+}
+function renderActionOf(path, action, env) {
+    const { schema, reads, rowName, warnings } = env;
+    if (action.$action === 'channel') {
+        // Not on this channel (a transfer by text): the types keep it to `ctx.call`, so reaching here is a bug.
+        if (env.channel !== undefined && env.channel !== 'call' && CALL_ONLY.has(action.channel)) {
+            throw new PageDocumentError(`${path}: ${action.channel} is a call action, and this is ${env.channel} (use ctx.call only on the call page)`);
+        }
+        return channelButton(path, action);
+    }
+    if (action.$action === 'createRow') {
+        const table = getCompiledTable(schema, action.table);
+        if (!table)
+            throw new PageDocumentError(`${path}: createRow on ${action.table}, not a table of this sequence`);
+        const parent = parentOf(table);
+        for (const key of Object.keys(action.prefill)) {
+            if (!getTableField(table, key))
+                throw new PageDocumentError(`${path}: createRow(${action.table}) prefills ${key}, not a field of it`);
+        }
+        const properties = {};
+        for (const fieldName of action.fields) {
+            if (!getTableField(table, fieldName))
+                throw new PageDocumentError(`${path}: createRow field ${action.table}.${fieldName} is not in this sequence`);
+            if (parent?.field === fieldName)
+                throw new PageDocumentError(`${path}: the parent ${fieldName} is prefilled, not a field to fill`);
+            if (fieldName in action.prefill)
+                continue;
+            properties[fieldName] = expandParam(path, { $schemaField: `${action.table}.${fieldName}` }, env);
+        }
+        // Where the new row hangs: prefilled, else the one parent this run's reads of the table were anchored on.
+        let parentId = null;
+        if (parent) {
+            const preset = action.prefill[parent.field];
+            const parents = reads.parentsOf(action.table);
+            parentId = typeof preset === 'string' ? preset : parents.length === 1 ? parents[0] : null;
+            if (!parentId) {
+                warnings.push(`${path}: createRow(${action.table}) needs ${parent.field} prefilled: this run read ${parents.length} parents of it; left off the page`);
+                return null;
+            }
+            // The parent row must be a row this run read, of the parent field's table: it goes on the page,
+            // so pressing the button can write under it.
+            const parentRow = reads.row(parentId);
+            if (!parentRow || parentRow.table !== parent.table) {
+                warnings.push(`${path}: createRow(${action.table}) parent ${parentId} is not a ${parent.table} row this run read; left off the page`);
+                return null;
+            }
+            rowName(parentRow.table, parentId);
+        }
+        const set = { ...action.prefill };
+        if (parent)
+            delete set[parent.field];
+        const under = parent && parentId ? ` under ${rowName(parent.table, parentId)}` : '';
+        return {
+            id: path,
+            kind: 'createRow',
+            name: action.label ?? `Add ${table.label}`,
+            description: action.description ?? `Adds a new ${table.label} (${action.table})${under}.`,
+            input: { type: 'object', properties, required: action.required.filter((r) => r in properties) },
+            server: { kind: 'createRow', table: action.table, parentId, set, fields: action.fields, required: action.required },
+        };
+    }
+    if (action.$action === 'deleteRow') {
+        const read = reads.row(action.rowId);
+        if (!read) {
+            warnings.push(`${path}: deleteRow on a row this run did not read; left off the page`);
+            return null;
+        }
+        const name = rowName(read.table, action.rowId);
+        return {
+            id: path,
+            kind: 'deleteRow',
+            name: action.label ?? `Delete ${name}`,
+            description: action.description ?? `Delete ${name} and everything under it.`,
+            input: null,
+            server: { kind: 'deleteRow', table: read.table, rowId: action.rowId, ...(action.reason ? { reason: action.reason } : {}) },
+        };
+    }
+    if (action.$action === 'message')
+        return messageButton(path, action, env);
+    if (action.$action === 'followUp')
+        return followUpButton(path, action);
+    if (action.$action === 'function') {
+        const { input, prefill } = actionInput(path, action.name, action.parameters, action.prefill ?? {}, env);
+        return {
+            id: path,
+            kind: 'function',
+            name: action.label ?? action.name,
+            description: action.description ?? `Runs ${action.name}.`,
+            input,
+            server: { kind: 'function', name: action.name, ...(action.say ? { say: action.say } : {}), ...(Object.keys(prefill).length ? { prefill } : {}) },
+        };
+    }
+    const { input, prefill } = actionInput(path, action.name, action.parameters, action.prefill, env);
+    return {
+        id: path,
+        kind: 'custom',
+        name: action.name,
+        description: action.description,
+        input,
+        server: { kind: 'custom', name: action.name, prefill },
+    };
+}
+/**
+ * What the AI fills of an action's parameters, and what the page fixed. A prefilled row is checked and
+ * put on the page; a `choose(...)` (25 §10) becomes the AI's choice among exactly those rows, each shown
+ * with its label.
+ */
+function actionInput(path, name, parameters, given, env) {
+    const declared = parameters?.properties ?? {};
+    const properties = {};
+    const prefill = {};
+    for (const key of Object.keys(given)) {
+        if (!(key in declared))
+            throw new PageDocumentError(`${path}: ${name} prefills ${key}, not one of its parameters`);
+    }
+    for (const [key, param] of Object.entries(declared)) {
+        const value = given[key];
+        if (isChoose(value)) {
+            properties[key] = chooseParam(`${path}: ${name}({ ${key} })`, param, value, env);
+            continue;
+        }
+        if (key in given) {
+            checkPrefill(`${path}: ${name}({ ${key} })`, param, value, env);
+            prefill[key] = value;
+            continue;
+        }
+        properties[key] = expandParam(`${path}.${key}`, param, env);
+    }
+    const input = Object.keys(properties).length
+        ? { type: 'object', properties, required: (parameters?.required ?? []).filter((r) => r in properties) }
+        : null;
+    return { input, prefill };
+}
+/** A row parameter's candidates, as `choose(...)` gave them: rows this run read, of the parameter's table. */
+function chooseParam(where, param, chosen, env) {
+    const table = isSchemaFieldParam(param) ? rowTableOf(where, param, env.schema) : null;
+    if (!table)
+        throw new PageDocumentError(`${where}: choose(...) is for a row parameter (schemaField('table.id') or a lookup)`);
+    if (chosen.table !== null && chosen.table !== table)
+        throw new PageDocumentError(`${where}: choose(...) gives ${chosen.table} rows, the parameter takes ${table}`);
+    const names = [];
+    const labels = {};
+    for (const option of chosen.options) {
+        const read = env.reads.row(option.id);
+        if (!read || read.table !== table)
+            throw new PageDocumentError(`${where}: choose(...) offers ${option.id}, not a ${table} row this run read`);
+        const rowName = env.rowName(table, option.id);
+        names.push(rowName);
+        labels[rowName] = option.label;
+    }
+    // Each row with its label, as a ref field's candidates are written (26 §16.2 #7).
+    const help = isSchemaFieldParam(param) ? (param.extraction ?? schemaFieldOf(where, param, env.schema).def?.extraction) : undefined;
+    return { type: 'ref', table, enum: names, labels, ...(help ? { description: help } : {}) };
+}
+/** `table.field` of a schema-field parameter, checked against this sequence. */
+function schemaFieldOf(where, param, schema) {
+    const [table, field, ...rest] = param.$schemaField.split('.');
+    const def = table ? getCompiledTable(schema, table) : undefined;
+    if (!table || !field || rest.length || !def)
+        throw new PageDocumentError(`${where}: schemaField('${param.$schemaField}') is not a table.field of this sequence`);
+    if (field === 'id')
+        return { table, field, def: null };
+    const fieldDef = getTableField(def, field);
+    if (!fieldDef)
+        throw new PageDocumentError(`${where}: schemaField('${param.$schemaField}') is not a field of this sequence`);
+    return { table, field, def: fieldDef };
+}
+/** The table a parameter chooses a row of (`table.id`, a lookup), or null. */
+function rowTableOf(where, param, schema) {
+    const { table, def } = schemaFieldOf(where, param, schema);
+    if (!def)
+        return table;
+    return def.ref ? def.ref.table : null;
+}
+/** A parameter as JSON Schema for the AI: schema fields filled in from the schema, row choices as enums. */
+function expandParam(where, param, env) {
+    if (isSchemaFieldParam(param)) {
+        const rowTable = rowTableOf(where, param, env.schema);
+        const { table, def } = schemaFieldOf(where, param, env.schema);
+        if (rowTable) {
+            const names = env.rowsOnPage(rowTable);
+            const help = param.extraction ?? def?.extraction;
+            return { type: 'ref', table: rowTable, enum: names, ...(help ? { description: help } : {}) };
+        }
+        // The page's extraction replaces the schema's; type and allowed values stay the schema's.
+        const fieldDef = param.extraction !== undefined ? { ...def, extraction: param.extraction } : def;
+        return fieldDef.dataType === 'contact_schedule' ? scheduleProperty(fieldDef) : scalarProperty(fieldDef);
+    }
+    if (param.type === 'array') {
+        const out = { type: 'array', items: expandParam(`${where}[]`, param.items, env) };
+        if (param.description)
+            out.description = param.description;
+        return out;
+    }
+    if (param.type === 'object') {
+        const properties = {};
+        for (const [key, child] of Object.entries(param.properties))
+            properties[key] = expandParam(`${where}.${key}`, child, env);
+        const out = { type: 'object', properties };
+        if (param.required)
+            out.required = [...param.required];
+        if (param.description)
+            out.description = param.description;
+        return out;
+    }
+    return { ...param };
+}
+/**
+ * A prefilled row argument, at any depth (`{ target: { id } }`, a list of rows), must be a row this run
+ * read, of its table: it then goes on the page, so the action may write it.
+ */
+function checkPrefill(where, param, value, env) {
+    if (value === null || value === undefined)
+        return;
+    if (isSchemaFieldParam(param)) {
+        const rowTable = rowTableOf(where, param, env.schema);
+        if (!rowTable)
+            return;
+        const read = typeof value === 'string' ? env.reads.row(value) : undefined;
+        if (!read || read.table !== rowTable)
+            throw new PageDocumentError(`${where} is not a ${rowTable} row this run read`);
+        env.rowName(read.table, value);
+        return;
+    }
+    if (param.type === 'array') {
+        if (!Array.isArray(value))
+            throw new PageDocumentError(`${where} must be a list`);
+        value.forEach((item, i) => checkPrefill(`${where}[${i}]`, param.items, item, env));
+        return;
+    }
+    if (param.type === 'object') {
+        if (!isPlainObject(value))
+            throw new PageDocumentError(`${where} must be an object`);
+        for (const [key, child] of Object.entries(param.properties))
+            checkPrefill(`${where}.${key}`, child, value[key], env);
+    }
+}
+/** A schema field's argument: the field's own type and options. */
+function scalarProperty(def) {
+    const help = describeField(def);
+    if (def.dataType === 'multi_select')
+        return { type: 'multi_select', enum: def.options ?? [], ...help };
+    if (def.dataType === 'select')
+        return { type: 'select', enum: def.options ?? [], ...help };
+    return { type: def.dataType, ...help };
+}
+/** A `contact_schedule` field: its own structure (`ContactSchedule`), not text. */
+function scheduleProperty(def) {
+    const window = {
+        type: 'object',
+        properties: {
+            start: { type: 'string', description: 'HH:mm' },
+            end: { type: 'string', description: 'HH:mm, after start; may be 24:00' },
+        },
+        required: ['start', 'end'],
+    };
+    const windows = { type: 'array', items: window, description: 'sorted by start, not overlapping; empty: no contact' };
+    const days = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'];
+    return {
+        type: 'object',
+        'x-type': 'contact_schedule',
+        ...describeField(def),
+        properties: {
+            weekly: {
+                type: 'object',
+                nullable: true,
+                description: 'all seven weekdays; null: no weekly restriction',
+                properties: Object.fromEntries(days.map((day) => [day, windows])),
+                required: [...days],
+            },
+            dateOverrides: {
+                type: 'array',
+                description: 'dates whose windows replace weekly',
+                items: {
+                    type: 'object',
+                    properties: { dates: { type: 'array', items: { type: 'string', description: 'YYYY-MM-DD' } }, windows },
+                    required: ['dates', 'windows'],
+                },
+            },
+        },
+        required: ['weekly', 'dateOverrides'],
+    };
+}
+/**
+ * An argument's help (26 §16.2 #5a): how to fill it, the page's (`schemaField(…, { extraction })`) or else
+ * the field's; none when neither says. The label is not repeated in it; how its type is written is the
+ * system message's (26 §15.8).
+ */
+function describeField(def) {
+    return def.extraction ? { description: def.extraction } : {};
+}
+// ---------------------------------------------------------------------------------------------
+function join(path, key) {
+    return path ? `${path}.${key}` : key;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(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 isFieldCell(value) {
+    return isPlainObject(value) && value.$field === true;
+}
+function isRefFieldCell(value) {
+    return isPlainObject(value) && value.$refField === true && Array.isArray(value.options);
+}
+function isAction(value) {
+    return (isPlainObject(value) &&
+        (value.$action === 'createRow' ||
+            value.$action === 'deleteRow' ||
+            value.$action === 'custom' ||
+            (value.$action === 'function' && typeof value.name === 'string') ||
+            (value.$action === 'message' && typeof value.key === 'string') ||
+            (value.$action === 'followUp' && Array.isArray(value.channels)) ||
+            (value.$action === 'channel' && typeof value.channel === 'string')));
+}
+/** The page function returned an action to run now (`perform(…)`, or the action itself). */
+function performOf(document) {
+    if (isPlainObject(document) && document.$perform === true && isAction(document.action))
+        return document;
+    if (isAction(document))
+        return { $perform: true, action: document };
+    return null;
+}
+/**
+ * The run key of a button on the page (17b §7): the action's own key, whoever runs it — the model
+ * pressing it, or the page function returning it — not its place on the page, which moves with rows.
+ */
+export function runKeyOf(action) {
+    const server = action.server;
+    if (server.kind === 'custom')
+        return server.name;
+    if (server.kind === 'createRow')
+        return `createRow:${server.table}`;
+    if (server.kind === 'deleteRow')
+        return `deleteRow:${server.rowId}`;
+    if (server.kind === 'function')
+        return server.name;
+    if (server.kind === 'message' || server.kind === 'followUp')
+        return server.key;
+    return actionKey(server.spec);
+}
+/** The run key of an action the page function returned, when it names none. */
+export function actionKey(action) {
+    if (action.$action === 'custom')
+        return action.name;
+    if (action.$action === 'function')
+        return action.name;
+    if (action.$action === 'message' || action.$action === 'followUp')
+        return action.key;
+    if (action.$action === 'createRow')
+        return `createRow:${action.table}`;
+    if (action.$action === 'deleteRow')
+        return `deleteRow:${action.rowId}`;
+    if (action.channel === 'keypad' || action.channel === 'announce')
+        return action.key;
+    return action.channel;
+}
+/** Marks removed with the todos (24 §2.3): a page still writing one is told what replaced it. */
+/** The marks a page object may carry: `$title`, `$description` on any block; `$guide`, `$extraction` on the root. */
+const KNOWN_MARKS = new Set(['$title', '$description', '$guide', '$extraction']);
+const REMOVED_MARKS = {
+    $say: 'write $guide on the page\'s root',
+    $done: 'show what is done as a result, or stop guiding to it',
+    $locked: 'leave out what the AI must not touch; say why in plain text',
+    $summary: 'nothing is folded any more',
+    $recommend: 'write $guide on the page\'s root',
+};
+/**
+ * The page's `$extraction` (26 §15.3): how to fill a field on this page, by `table.field`, replacing the
+ * schema's for every place it is on the page. One per field for the whole page, so a field means the
+ * same everywhere on it. A `table.field` the schema does not have is warned and left out.
+ */
+function pageExtractions(document, schema, warnings) {
+    const out = new Map();
+    const value = isPlainObject(document) ? document.$extraction : undefined;
+    if (value === undefined || value === null)
+        return out;
+    if (!isPlainObject(value))
+        throw new PageDocumentError('page: $extraction must be an object of table.field → text');
+    for (const [key, text] of Object.entries(value)) {
+        if (typeof text !== 'string')
+            throw new PageDocumentError(`page: $extraction['${key}'] must be text`);
+        const [table, field, ...rest] = key.split('.');
+        if (!table || !field || rest.length || !getCompiledTable(schema, table)?.fields[field]) {
+            warnings.push(`page: $extraction['${key}'] is not a table.field of the schema; left out`);
+            continue;
+        }
+        out.set(key, text);
+    }
+    return out;
+}
+/** `$guide` and `$extraction` on the root (24 §2.1, 26 §15.3); on any other block they are refused, as the removed marks are. */
+function pageMarks(block, value, path, isRoot, warnings) {
+    const where = path || 'page';
+    for (const [mark, instead] of Object.entries(REMOVED_MARKS)) {
+        if (value[mark] !== undefined)
+            throw new PageDocumentError(`${where}: ${mark} was removed (24 §2.3): ${instead}`);
+    }
+    // A misspelt mark (`$titel`) would otherwise do nothing, silently (26 §16.2 #4).
+    for (const mark of Object.keys(value)) {
+        if (mark.startsWith('$') && !KNOWN_MARKS.has(mark))
+            warnings.push(`${where}: ${mark} is not a page mark (${[...KNOWN_MARKS].join(', ')}); ignored`);
+    }
+    if (!isRoot && value.$extraction !== undefined)
+        throw new PageDocumentError(`${where}: $extraction is the page's: write it on the page's root, one per page (26 §15.3)`);
+    if (value.$guide === undefined || value.$guide === null)
+        return;
+    if (typeof value.$guide !== 'string')
+        throw new PageDocumentError(`${where}: $guide must be text`);
+    if (!isRoot)
+        throw new PageDocumentError(`${where}: $guide is the page's: write it on the page's root, one per page (24 §2.1)`);
+    if (value.$guide.trim())
+        block.guide = value.$guide;
+}
+const CHANNEL_NAMES = {
+    transfer: ['Transfer to a person', 'Hand the call to a person. Press it only when the customer wants a person or the page says so.'],
+    keypad: ['Collect a keypress', 'The customer answers by pressing a key on their phone.'],
+    announce: ['Play a fixed statement', 'Plays a fixed statement, word for word.'],
+    end: ['End the conversation', 'Ends the conversation after your last line (say goodbye in the same step).'],
+    voicemail: ['Leave the voicemail', 'Leaves a fixed message after the beep, then hangs up.'],
+};
+const BACKGROUND_TRANSFER = [
+    'Call a person in the background',
+    'Calls a person while you keep helping the customer; the customer is put through once the person takes the call. Press it only when the customer wants a person or the page says so.',
+];
+/** A channel action as a button: nothing for the AI to fill; what it does stays on the server. */
+function channelButton(path, action) {
+    const [name, description] = action.channel === 'transfer' && action.mode === 'background' ? BACKGROUND_TRANSFER : CHANNEL_NAMES[action.channel];
+    const label = 'label' in action ? action.label : undefined;
+    const text = 'description' in action ? action.description : undefined;
+    return {
+        id: path,
+        kind: 'channel',
+        name: label ?? name,
+        description: text ?? (action.channel === 'keypad' ? `${description} It says: "${action.say}"` : description),
+        input: null,
+        server: { kind: 'channel', spec: action },
+    };
+}
+/**
+ * A text or an email as a button (25 §8): the contact it goes to must be a contact row this run read (it
+ * goes on the page); what the page left out (`body`, an email's `subject`) the AI fills.
+ */
+function messageButton(path, action, env) {
+    if (action.to !== undefined) {
+        const read = env.reads.row(action.to);
+        if (!read || read.table !== 'contact') {
+            env.warnings.push(`${path}: ${action.key} goes to ${action.to}, not a contact this run read; left off the page`);
+            return null;
+        }
+        env.rowName('contact', action.to);
+    }
+    const what = action.channel === 'sms' ? 'text' : 'email';
+    const properties = {};
+    if (action.channel === 'email' && action.subject === undefined)
+        properties.subject = { type: 'string', description: 'The email\'s subject line' };
+    if (action.body === undefined)
+        properties.body = { type: 'string', description: `The ${what} to send, in full, in the customer's language` };
+    const to = action.to !== undefined ? env.rowName('contact', action.to) : 'the customer';
+    const server = { kind: 'message', channel: action.channel, key: action.key, to: action.to ?? null };
+    if (action.body !== undefined)
+        server.body = action.body;
+    if (action.subject !== undefined)
+        server.subject = action.subject;
+    if (action.say !== undefined)
+        server.say = action.say;
+    return {
+        id: path,
+        kind: 'message',
+        name: action.label ?? (action.channel === 'sms' ? 'Send a text' : 'Send an email'),
+        description: action.description ??
+            (action.body !== undefined
+                ? `Sends the fixed ${what} "${action.label ?? action.key}" to ${to} now.`
+                : `Sends a ${what} you write to ${to} now.`),
+        input: Object.keys(properties).length ? { type: 'object', properties, required: Object.keys(properties) } : null,
+        server,
+    };
+}
+const CHANNEL_WORDS = { call: 'a call', sms: 'a text', email: 'an email' };
+/** The follow-up button (25 §5): the AI gives the channel, the time and the customer's own words. */
+function followUpButton(path, action) {
+    const ways = action.channels.map((c) => CHANNEL_WORDS[c]).join(' or ');
+    return {
+        id: path,
+        kind: 'followUp',
+        name: action.label ?? 'Book the follow-up they asked for',
+        description: action.description ??
+            `The customer asked for ${ways} later, or agreed to one, at a time they said: press it then, and tell them it is booked. Not for a follow-up they did not ask for.`,
+        input: {
+            type: 'object',
+            properties: {
+                channel: { type: 'select', enum: [...action.channels], description: 'How they want to be reached' },
+                at: { type: 'datetime', description: 'When, as they said it, with the offset of their time zone; for a vague time ("tomorrow afternoon") a time inside it' },
+                customer_quote: { type: 'string', description: 'Their own words asking for it or agreeing to it, as said' },
+                note: { type: 'string', description: 'What it is for, in a few words' },
+            },
+            required: ['channel', 'at', 'customer_quote'],
+        },
+        server: { kind: 'followUp', key: action.key, channels: [...action.channels] },
+    };
+}
+function isSchemaFieldParam(value) {
+    return isPlainObject(value) && typeof value.$schemaField === 'string';
+}
+function isRowLike(value) {
+    return typeof value.id === 'string' && Object.values(value).some(isSlotLike);
+}
+function displayable(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+        return value;
+    return JSON.stringify(value);
+}
+/**
+ * The page to show when the page script failed (15 §10.9): the last good page, every cell read-only
+ * and no actions, marked stale; without one, an empty page.
+ */
+export function fallbackPage(last, reason) {
+    if (!last) {
+        return {
+            root: { kind: 'block', key: '', path: '', list: false, children: [] },
+            cells: {},
+            actions: {},
+            rows: {},
+            warnings: [reason],
+            fallback: { reason, stale: false },
+        };
+    }
+    const readOnly = (node) => node.kind === 'cell'
+        ? { ...node, readOnly: true }
+        : node.kind === 'action'
+            ? null
+            : node.kind === 'block'
+                ? { ...node, children: node.children.map(readOnly).filter((n) => n !== null) }
+                : node;
+    return {
+        root: readOnly(last.root),
+        cells: Object.fromEntries(Object.entries(last.cells).map(([id, cell]) => [id, { ...cell, writable: false }])),
+        actions: {},
+        rows: last.rows,
+        ...(last.extractions ? { extractions: last.extractions } : {}),
+        warnings: [...last.warnings, reason],
+        fallback: { reason, stale: true },
+    };
+}
+//# sourceMappingURL=render.js.map