@texuli/spec 0.3.0 → 0.5.0

package/dist/validate.js

@@ -1,15 +1,23 @@
+import { ACTION_FIELDS, contractRoot, DATA_BINDING_KEY, SPEC_ACTION_OPS, SPEC_LIMITS, SPEC_REGEX, SPEC_STATE_TYPES, STATE_BINDING_KEY, STATE_FIELDS, toDialectSchema, } from "./contract.js";
 import { isRecord, validateInstance } from "./dialect.js";
+import { checkStateSurface, surfaceInputs } from "./surface.js";
 const MAX_TREE_DEPTH = 64;
+const ACTION_KEYS = new Set(Object.values(ACTION_FIELDS).flatMap((f) => f.allowed));
+const STATE_KEYS = new Set(Object.values(STATE_FIELDS).flat());
+const FORM_ID = 'action-form';
+const BINDING_SHAPE = 'A binding is exactly {"$state": name} or {"$data": name}.';
 /**
  * Validate a blueprint envelope against the spec alone: the envelope schema,
- * then every node against the catalog vocabulary (closed ids, closed prop
- * names, prop kinds and enum values, required props, no platform-extension
- * props from data, a `slot` that names a slot prop of the parent) and the
- * declared profile. A `when` condition is checked for shape only; the
- * runtime formula parser checks its operands. With `catalogHash`, an envelope
- * bound to another catalog is refused. This is the shared, target-neutral
- * contract; URL policy, limits, grammar and rendering stay in the runtime
- * validators (`@texuli/catalog/validate`).
+ * the declared state and flow, then every node against the catalog
+ * vocabulary (closed ids, closed prop names, prop kinds and enum values,
+ * property schemas, required props, no platform-extension props from data,
+ * a `slot` that names a slot prop of the parent, bindings, two-way `bind`,
+ * `on` events and their closed actions) and the declared profile. A `when`
+ * condition is checked for shape only; the runtime formula parser checks
+ * its operands. With `catalogHash`, an envelope bound to another catalog is
+ * refused. Deprecated components and props add `warnings` (never failing).
+ * This is the shared, target-neutral contract; URL policy, limits, grammar
+ * and rendering stay in the runtime validators (`@texuli/catalog/validate`).
  */
 export function validateBlueprint(input, documents, options = {}) {
     const diagnostics = validateInstance(documents.blueprintSchema, input).map((issue) => ({ code: 'schema', path: issue.path, message: `${issue.code}: ${issue.message}` }));
@@ -22,49 +30,312 @@ export function validateBlueprint(input, documents, options = {}) {
             message: 'The blueprint is bound to another catalog.',
         });
     }
+    const { workflowSchema: schema, validateWorkflowGraph: validate } = documents;
+    const workflow = schema && validate ? { schema, validate } : undefined;
+    const state = checkStateDeclarations(input.state, diagnostics, workflow);
+    const flow = checkFlow(input.flow, diagnostics);
+    const warnings = [];
     const portable = input.profile === 'portable';
     if (isRecord(input.tree)) {
-        diagnostics.push(...validateTree(input.tree, documents.catalog, { portable, path: '$.tree' }));
+        // The state surface's node rules, as the player refuses them at paint time.
+        for (const issue of checkStateSurface(input.tree, surfaceInputs(input))) {
+            diagnostics.push({
+                code: issue.code,
+                path: `$.tree${issue.at.map((index) => `.children[${index}]`).join('')}`,
+                message: issue.message,
+            });
+        }
+        diagnostics.push(...validateTree(input.tree, documents.catalog, {
+            portable,
+            path: '$.tree',
+            state,
+            flow,
+            root: contractRoot(documents.blueprintSchema, workflow?.schema),
+            workflow,
+            warnings,
+        }));
+    }
+    return {
+        ok: diagnostics.length === 0,
+        diagnostics,
+        ...(warnings.length > 0 ? { warnings } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// State and flow
+/**
+ * Read the envelope's `state` (code `state`): at most 64 variables, safe
+ * names, the fields each type takes, and an initial value of the declared
+ * type. One diagnostic per refused declaration; a refused declaration stays
+ * declared (so bindings to it are not also `unknown-state`). Shape problems
+ * the schema reports are not repeated.
+ */
+export function checkStateDeclarations(input, out, workflow) {
+    const declared = new Map();
+    if (!isRecord(input))
+        return declared;
+    const names = Object.keys(input);
+    if (names.length > SPEC_LIMITS.stateVars) {
+        out.push({
+            code: 'state',
+            path: '$.state',
+            message: `At most ${SPEC_LIMITS.stateVars} state variables (got ${names.length}).`,
+        });
+    }
+    for (const name of names) {
+        const path = `$.state.${name}`;
+        if (!SPEC_REGEX.stateName.test(name)) {
+            out.push({
+                code: 'state',
+                path,
+                message: `"${name}" is not a valid state name.`,
+            });
+            continue;
+        }
+        const raw = input[name];
+        if (!isRecord(raw) || !SPEC_STATE_TYPES.includes(raw.type))
+            continue;
+        const variable = readDeclaration(name, raw, path, out, workflow);
+        declared.set(name, variable);
+    }
+    return declared;
+}
+function readDeclaration(name, raw, path, out, workflow) {
+    const type = raw.type;
+    const writable = raw.source === undefined;
+    const refuse = (where, message) => {
+        out.push({ code: 'state', path: where, message });
+        return { type, valid: false, initial: undefined, writable };
+    };
+    const accept = (initial, bounds) => ({
+        type,
+        valid: true,
+        initial,
+        writable,
+        ...bounds,
+    });
+    // Unknown keys are the schema's to report; only fields of another type are judged here.
+    const extra = Object.keys(raw).find((key) => STATE_KEYS.has(key) && !STATE_FIELDS[type].includes(key));
+    if (extra !== undefined)
+        return refuse(`${path}.${extra}`, `A ${type} variable takes no "${extra}".`);
+    const has = (key) => Object.hasOwn(raw, key);
+    switch (type) {
+        case 'boolean': {
+            const initial = has('initial') ? raw.initial : false;
+            if (typeof initial !== 'boolean')
+                return refuse(`${path}.initial`, `"${name}" needs a boolean.`);
+            return accept(initial);
+        }
+        case 'number': {
+            const { min, max } = raw;
+            if (!finite(min) || !finite(max) || min > max) {
+                return refuse(path, `"${name}" needs finite min ≤ max.`);
+            }
+            const initial = has('initial') ? raw.initial : min;
+            if (!finite(initial) || initial < min || initial > max) {
+                return refuse(`${path}.initial`, `"${name}" initial must be between ${min} and ${max}.`);
+            }
+            return accept(initial, { min, max });
+        }
+        case 'enum': {
+            const values = raw.values;
+            if (!Array.isArray(values))
+                return refuse(path, `"${name}" needs values.`);
+            if (new Set(values).size !== values.length) {
+                return refuse(`${path}.values`, `"${name}" values must be distinct.`);
+            }
+            const initial = has('initial') ? raw.initial : values[0];
+            if (typeof initial !== 'string' || !values.includes(initial)) {
+                return refuse(`${path}.initial`, `"${name}" initial must be one of its values.`);
+            }
+            return accept(initial, { values: values });
+        }
+        case 'string': {
+            const maxLength = has('maxLength')
+                ? raw.maxLength
+                : SPEC_LIMITS.defaultStringLength;
+            const initial = has('initial') ? raw.initial : '';
+            if (typeof initial !== 'string' || initial.length > maxLength) {
+                return refuse(`${path}.initial`, `"${name}" initial must be a string of at most ${maxLength}.`);
+            }
+            return accept(initial, { maxLength });
+        }
+        case 'list': {
+            const maxItems = has('maxItems') ? raw.maxItems : SPEC_LIMITS.listItems;
+            const initial = has('initial') ? raw.initial : [];
+            const problem = listProblem(initial, maxItems);
+            if (problem)
+                return refuse(`${path}.initial${problem.at}`, problem.message);
+            return accept(initial, { maxItems });
+        }
+        case 'workflow': {
+            if (!has('initial'))
+                return refuse(path, `"${name}" needs an initial workflow graph.`);
+            if (!workflow) {
+                return refuse(`${path}.initial`, 'Workflow state needs the workflow schema and validator.');
+            }
+            const result = workflow.validate(raw.initial, workflow.schema);
+            for (const d of result.diagnostics) {
+                out.push({ ...d, path: `${path}.initial${d.path.slice(1)}` });
+            }
+            return { type, valid: result.ok, initial: raw.initial, writable };
+        }
+    }
+}
+/**
+ * A list value: at most `maxItems` items, each `{ id, ...fields }` with a
+ * unique item key and at most 16 scalar fields (string ≤ 1000, finite
+ * number, boolean) named like state variables. Strings follow the
+ * `listText` rule: a draggable item's text never hides or reorders itself.
+ */
+export function listProblem(value, maxItems) {
+    if (!Array.isArray(value))
+        return { at: '', message: 'A list value is an array of items.' };
+    if (value.length > maxItems)
+        return { at: '', message: `At most ${maxItems} items.` };
+    const ids = new Set();
+    for (const [index, item] of value.entries()) {
+        const at = `[${index}]`;
+        if (!isRecord(item) || typeof item.id !== 'string' || !SPEC_REGEX.itemKey.test(item.id)) {
+            return { at, message: 'An item is an object with an item key "id".' };
+        }
+        if (ids.has(item.id))
+            return { at: `${at}.id`, message: `Item "${item.id}" appears twice.` };
+        ids.add(item.id);
+        const fields = Object.keys(item).filter((key) => key !== 'id');
+        if (fields.length > SPEC_LIMITS.listItemFields) {
+            return { at, message: `At most ${SPEC_LIMITS.listItemFields} fields besides "id".` };
+        }
+        for (const key of fields) {
+            const field = item[key];
+            const ok = SPEC_REGEX.stateName.test(key) &&
+                (typeof field === 'boolean' ||
+                    finite(field) ||
+                    (typeof field === 'string' && field.length <= SPEC_LIMITS.stringLength));
+            if (!ok) {
+                return {
+                    at: `${at}.${key}`,
+                    message: 'Item fields are named scalars (strings of at most 1000).',
+                };
+            }
+            if (typeof field === 'string' && !SPEC_REGEX.listText.test(field)) {
+                return {
+                    at: `${at}.${key}`,
+                    message: 'Item text cannot hold control, bidirectional or invisible formatting characters.',
+                };
+            }
+        }
     }
-    return { ok: diagnostics.length === 0, diagnostics };
+    return null;
+}
+/**
+ * Read the envelope's `flow` (code `state`): distinct views, an initial and
+ * transitions that name declared views (or `*` as a source).
+ */
+export function checkFlow(input, out) {
+    if (!isRecord(input) || !Array.isArray(input.views))
+        return null;
+    const views = input.views.filter((view) => typeof view === 'string');
+    const fail = (path, message) => out.push({ code: 'state', path, message });
+    if (new Set(views).size !== views.length)
+        fail('$.flow.views', 'Flow views must be distinct.');
+    if (input.initial !== undefined && !views.includes(input.initial)) {
+        fail('$.flow.initial', 'flow.initial must be one of the declared views.');
+    }
+    const events = new Set();
+    if (Array.isArray(input.transitions)) {
+        input.transitions.forEach((transition, index) => {
+            if (!isRecord(transition))
+                return;
+            const path = `$.flow.transitions[${index}]`;
+            const { from, to, on } = transition;
+            if (typeof from === 'string' && from !== '*' && !views.includes(from)) {
+                fail(`${path}.from`, 'from must be a declared view or "*".');
+            }
+            if (typeof to === 'string' && !views.includes(to))
+                fail(`${path}.to`, 'to must be a declared view.');
+            if (typeof on === 'string')
+                events.add(on);
+        });
+    }
+    return { views, events };
+}
+/** A context reporting into `out`. */
+function reportInto(context) {
+    return {
+        ...context,
+        fail: (code, path, message) => context.out.push({ code, path, id: context.id, message }),
+    };
 }
 /** Check one catalog tree against the vocabulary. See {@link validateBlueprint}. */
 export function validateTree(tree, catalog, options = {}) {
     const byId = new Map(catalog.components.map((c) => [c.id, c]));
     const out = [];
-    const visit = (node, path, depth, parent) => {
+    const state = options.state ?? new Map();
+    const flow = options.flow ?? null;
+    const root = options.root ?? { $defs: {} };
+    const warn = (warning) => options.warnings?.push(warning);
+    const visit = (node, path, depth, parent, insideForm) => {
         if (!isRecord(node) || typeof node.id !== 'string' || depth > MAX_TREE_DEPTH)
             return;
         checkSlot(node.slot, parent, node.id, path, out);
         const component = byId.get(node.id);
+        const context = reportInto({
+            id: node.id,
+            state,
+            flow,
+            root,
+            insideForm,
+            out,
+            workflow: options.workflow,
+        });
         if (!component) {
-            out.push({
-                code: 'unknown-id',
-                path: `${path}.id`,
-                id: node.id,
-                message: `"${node.id}" is not in the catalog.`,
-            });
+            context.fail('unknown-id', `${path}.id`, `"${node.id}" is not in the catalog.`);
         }
         else {
             if (options.portable && component.capability !== 'portable-core') {
-                out.push({
-                    code: 'unsupported-profile',
-                    path,
-                    id: node.id,
-                    message: `"${node.id}" is ${component.capability}, not portable core.`,
-                });
+                context.fail('unsupported-profile', path, `"${node.id}" is ${component.capability}, not portable core.`);
+            }
+            const props = isRecord(node.props) ? node.props : {};
+            const bind = isRecord(node.bind) ? node.bind : {};
+            checkProps(props, bind, component, `${path}.props`, context);
+            checkBind(bind, props, component, `${path}.bind`, context);
+            if (isRecord(node.on))
+                checkOn(node.on, component, `${path}.on`, context);
+            if (component.deprecated) {
+                warn(deprecation(`${path}.id`, node.id, `"${node.id}"`, component.deprecated));
+            }
+            for (const prop of component.props) {
+                if (!prop.deprecated)
+                    continue;
+                const where = Object.hasOwn(props, prop.name)
+                    ? `${path}.props.${prop.name}`
+                    : Object.hasOwn(bind, prop.name)
+                        ? `${path}.bind.${prop.name}`
+                        : undefined;
+                if (where)
+                    warn(deprecation(where, node.id, `"${prop.name}"`, prop.deprecated));
             }
-            checkProps(node.props, component, `${path}.props`, out);
         }
         if (Array.isArray(node.children)) {
+            const inside = insideForm || node.id === FORM_ID;
             node.children.forEach((child, index) => {
-                visit(child, `${path}.children[${index}]`, depth + 1, component);
+                visit(child, `${path}.children[${index}]`, depth + 1, component, inside);
             });
         }
     };
-    visit(tree, options.path ?? '$', 0, null);
+    visit(tree, options.path ?? '$', 0, null, false);
     return out;
 }
+function deprecation(path, id, what, info) {
+    const instead = info.replacement ? `; use "${info.replacement}"` : '';
+    return {
+        code: 'deprecated',
+        path,
+        id,
+        message: `${what} is deprecated since ${info.since}${instead}.`,
+    };
+}
 /**
  * A node's `slot` (audit G04) must name a slot prop of its parent; omitted
  * or `children` is the default slot. A root fills no slot. An unknown
@@ -87,57 +358,447 @@ function checkSlot(slot, parent, id, path, out) {
             : `"${String(slot)}" is not a slot of "${parent.id}".`,
     });
 }
-function checkProps(props, component, path, out) {
-    const given = isRecord(props) ? props : {};
-    const id = component.id;
+function kindProblem(prop, value) {
+    const kindOk = prop.kind === 'string' || prop.kind === 'enum'
+        ? typeof value === 'string'
+        : prop.kind === 'number'
+            ? finite(value)
+            : prop.kind === 'boolean'
+                ? typeof value === 'boolean'
+                : prop.kind === 'array'
+                    ? Array.isArray(value)
+                    : prop.kind === 'object'
+                        ? isRecord(value)
+                        : false;
+    if (!kindOk)
+        return 'prop-type';
+    if (prop.kind === 'enum' && !(prop.enumValues ?? []).includes(value)) {
+        return 'enum-value';
+    }
+    return null;
+}
+/** Whether a value reads as a binding (`$state` or `$data` as an own key). */
+function isBindingShaped(value) {
+    return (isRecord(value) &&
+        (Object.hasOwn(value, STATE_BINDING_KEY) || Object.hasOwn(value, DATA_BINDING_KEY)));
+}
+/** The binding's key and name when it has exactly one key with a string name. */
+function bindingTarget(value) {
+    const keys = Object.keys(value);
+    const key = keys[0];
+    if (keys.length !== 1 || (key !== STATE_BINDING_KEY && key !== DATA_BINDING_KEY))
+        return null;
+    const name = value[key];
+    return typeof name === 'string' ? { key, name } : null;
+}
+function checkProps(given, bind, component, path, context) {
+    const { id, fail } = context;
     const declared = new Map(component.props.map((p) => [p.name, p]));
     for (const [name, value] of Object.entries(given)) {
         const here = `${path}.${name}`;
         const prop = declared.get(name);
         if (!prop) {
-            out.push({ code: 'unknown-prop', path: here, id, message: `"${id}" has no "${name}" prop.` });
+            fail('unknown-prop', here, `"${id}" has no "${name}" prop.`);
             continue;
         }
         if (prop.extension) {
-            out.push({
-                code: 'extension-prop',
-                path: here,
-                id,
-                message: `"${name}" is a ${prop.extension} extension (${prop.kind}) and cannot come from data.`,
-            });
+            fail('extension-prop', here, `"${name}" is a ${prop.extension} extension (${prop.kind}) and cannot come from data.`);
             continue;
         }
-        const kindOk = prop.kind === 'string' || prop.kind === 'enum'
-            ? typeof value === 'string'
-            : prop.kind === 'number'
-                ? typeof value === 'number' && Number.isFinite(value)
-                : prop.kind === 'boolean'
-                    ? typeof value === 'boolean'
-                    : prop.kind === 'array'
-                        ? Array.isArray(value)
-                        : prop.kind === 'object'
-                            ? isRecord(value)
-                            : false;
-        if (!kindOk) {
-            out.push({ code: 'prop-type', path: here, id, message: `"${name}" must be ${prop.kind}.` });
-        }
-        else if (prop.kind === 'enum' && !(prop.enumValues ?? []).includes(value)) {
-            out.push({
-                code: 'enum-value',
-                path: here,
-                id,
-                message: `"${name}" must be one of ${(prop.enumValues ?? []).join(', ')}.`,
-            });
+        if (isBindingShaped(value)) {
+            checkPropBinding(value, prop, here, context);
+            continue;
+        }
+        const problem = kindProblem(prop, value);
+        if (problem === 'prop-type') {
+            fail('prop-type', here, `"${name}" must be ${prop.kind}.`);
+        }
+        else if (problem === 'enum-value') {
+            fail('enum-value', here, `"${name}" must be one of ${(prop.enumValues ?? []).join(', ')}.`);
+        }
+        else if (prop.schema && (prop.kind === 'array' || prop.kind === 'object')) {
+            checkPropSchemaValue(prop.name, prop.schema, value, here, context);
+        }
+        else if (prop.kind === 'array' || prop.kind === 'object') {
+            walkOpaque(value, here, 0, context);
         }
     }
     for (const prop of component.props) {
-        if (prop.required && !prop.extension && !Object.hasOwn(given, prop.name)) {
-            out.push({
-                code: 'missing-required',
-                path: `${path}.${prop.name}`,
-                id,
-                message: `"${id}" needs "${prop.name}".`,
-            });
+        const given_ = Object.hasOwn(given, prop.name) || Object.hasOwn(bind, prop.name);
+        if (prop.required && !prop.extension && !given_) {
+            fail('missing-required', `${path}.${prop.name}`, `"${id}" needs "${prop.name}".`);
         }
     }
 }
+/** Whether `value` is a legal value of `prop` (kind, enum and property schema). */
+function fits(prop, value, root) {
+    if (kindProblem(prop, value) !== null)
+        return false;
+    if (prop.schema && (prop.kind === 'array' || prop.kind === 'object')) {
+        return validateInstance(toDialectSchema(prop.schema), value, root).length === 0;
+    }
+    return true;
+}
+/** A whole prop given as a binding: `$state` of a fitting variable, or `$data` for a scalar prop. */
+function checkPropBinding(value, prop, path, context) {
+    const { state } = context;
+    const target = bindingTarget(value);
+    const fail = (code, message) => context.fail(code, path, message);
+    if (!target) {
+        fail('binding', BINDING_SHAPE);
+        return;
+    }
+    if (target.key === DATA_BINDING_KEY) {
+        if (!SPEC_REGEX.dataName.test(target.name) || target.name.length > 64) {
+            fail('binding', `"${target.name}" is not a host data name.`);
+        }
+        else if (!['string', 'number', 'boolean', 'enum'].includes(prop.kind)) {
+            fail('binding', 'Host data binds only a whole string, number, boolean or enum prop.');
+        }
+        return;
+    }
+    const variable = state.get(target.name);
+    if (!variable) {
+        fail('unknown-state', `No state variable named "${target.name}".`);
+        return;
+    }
+    if (variable.valid && !fits(prop, variable.initial, context.root)) {
+        fail('binding', `"${target.name}" (${variable.type}) does not fit "${prop.name}" (${prop.kind}).`);
+    }
+}
+/**
+ * Nested bindings inside an array or object prop without a property schema:
+ * `$state` names must be declared; `$data` binds only a whole prop.
+ */
+function walkOpaque(value, path, depth, context) {
+    if (depth > SPEC_LIMITS.propDepth)
+        return;
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+            walkOpaque(item, `${path}[${index}]`, depth + 1, context);
+        });
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    if (isBindingShaped(value)) {
+        nestedBinding(value, path, context, undefined);
+        return;
+    }
+    for (const [key, item] of Object.entries(value))
+        walkOpaque(item, `${path}.${key}`, depth + 1, context);
+}
+/** A binding nested in a prop value; `schema` (when known) is the position's schema. */
+function nestedBinding(value, path, context, schema) {
+    const { state } = context;
+    const target = bindingTarget(value);
+    const fail = (code, message) => context.fail(code, path, message);
+    if (!target) {
+        fail('binding', BINDING_SHAPE);
+    }
+    else if (target.key === DATA_BINDING_KEY) {
+        fail('binding', 'Host data binds only a whole top-level prop.');
+    }
+    else {
+        const variable = state.get(target.name);
+        if (!variable)
+            fail('unknown-state', `No state variable named "${target.name}".`);
+        else if (schema &&
+            variable.valid &&
+            validateInstance(schema, variable.initial, context.root).length > 0) {
+            fail('binding', `"${target.name}" (${variable.type}) does not fit this position.`);
+        }
+    }
+}
+/**
+ * An array or object prop with a property schema: the dialect checks the
+ * value (its first issue is the prop's `prop-type`), then binding, reorder,
+ * action and workflow positions add their own diagnostics.
+ */
+function checkPropSchemaValue(name, propSchema, value, path, context) {
+    const { id, root } = context;
+    const defs = root.$defs ?? {};
+    const extra = [];
+    const sub = reportInto({ ...context, out: extra });
+    const at = (relative) => `${path}${relative.slice(1)}`;
+    const issues = validateInstance(toDialectSchema(propSchema), value, root, {
+        value(node, current, relative) {
+            if (node === defs.binding) {
+                if (isRecord(current) && Object.keys(current).length !== 1) {
+                    sub.fail('binding', at(relative), BINDING_SHAPE);
+                }
+                else if (isRecord(current) &&
+                    typeof current.$state === 'string' &&
+                    !context.state.has(current.$state)) {
+                    sub.fail('unknown-state', at(relative), `No state variable named "${current.$state}".`);
+                }
+                return undefined;
+            }
+            if (node === defs.reorder) {
+                if (isRecord(current) && isRecord(current.bind)) {
+                    reorderBinding(current.bind, at(`${relative}.bind`), sub);
+                }
+                return undefined;
+            }
+            if (node === defs.action) {
+                if (isRecord(current))
+                    checkAction(current, at(relative), undefined, sub);
+                return undefined;
+            }
+            if (node === defs.workflowGraph) {
+                // contractRoot adds workflowGraph only with a validator; a caller-built root fails closed here.
+                if (!context.workflow)
+                    return [{ code: 'bad-ref', path: relative, message: 'No validator.' }];
+                const schema = { ...node, $defs: defs };
+                const result = context.workflow.validate(current, schema);
+                const schemaIssues = [];
+                for (const d of result.diagnostics) {
+                    if (d.code === 'schema')
+                        schemaIssues.push({
+                            code: 'schema',
+                            path: `${relative}${d.path.slice(1)}`,
+                            message: d.message,
+                        });
+                    else
+                        extra.push({ ...d, path: at(`${relative}${d.path.slice(1)}`), id });
+                }
+                return schemaIssues;
+            }
+            if (isBindingShaped(current)) {
+                nestedBinding(current, at(relative), sub, node);
+                return [];
+            }
+            return undefined;
+        },
+    });
+    const first = issues[0];
+    if (first) {
+        context.fail('prop-type', at(first.path), `"${name}" does not match its schema: ${first.code}: ${first.message}`);
+    }
+    context.out.push(...extra);
+}
+/** `reorder.bind` must be `$state` of a writable list. */
+function reorderBinding(bind, path, context) {
+    const name = bind.$state;
+    if (typeof name !== 'string' || Object.keys(bind).length !== 1) {
+        if (typeof bind.$data === 'string') {
+            context.fail('binding', path, 'reorder needs a writable list, not host data.');
+        }
+        return;
+    }
+    const variable = context.state.get(name);
+    if (variable?.valid && (variable.type !== 'list' || !variable.writable)) {
+        context.fail('binding', path, `reorder binds a writable list; "${name}" is not one.`);
+    }
+}
+/** `bind`: two-way bindings to bindable props, `$state` only, writable and fitting. */
+function checkBind(bind, props, component, path, context) {
+    const { id, state } = context;
+    for (const [name, value] of Object.entries(bind)) {
+        const here = `${path}.${name}`;
+        const fail = (code, message) => context.fail(code, here, message);
+        const prop = component.props.find((p) => p.name === name);
+        if (!prop) {
+            fail('unknown-prop', `"${id}" has no "${name}" prop.`);
+            continue;
+        }
+        if (!(component.bindable ?? []).includes(name)) {
+            fail('binding', `"${name}" is not bindable on "${id}".`);
+            continue;
+        }
+        if (Object.hasOwn(props, name)) {
+            fail('binding', `"${name}" is set both as a prop and as a binding.`);
+            continue;
+        }
+        const target = isRecord(value) ? bindingTarget(value) : null;
+        if (!target || target.key !== STATE_BINDING_KEY) {
+            fail('binding', 'bind takes exactly {"$state": name}; host data is read-only.');
+            continue;
+        }
+        const variable = state.get(target.name);
+        if (!variable) {
+            fail('unknown-state', `No state variable named "${target.name}".`);
+            continue;
+        }
+        if (!variable.valid)
+            continue;
+        if (!variable.writable) {
+            fail('binding', `"${target.name}" is host-bound and read-only.`);
+        }
+        else if (!fits(prop, variable.initial, context.root)) {
+            fail('binding', `"${target.name}" (${variable.type}) does not fit "${name}" (${prop.kind}).`);
+        }
+    }
+}
+/** `on`: events the component declares, each with its closed actions. */
+function checkOn(on, component, path, context) {
+    for (const [event, actions] of Object.entries(on)) {
+        const here = `${path}.${event}`;
+        if (!(component.events ?? []).includes(event)) {
+            context.fail('unknown-event', here, `"${component.id}" fires no "${event}" event.`);
+        }
+        if (!Array.isArray(actions))
+            continue;
+        actions.forEach((action, index) => {
+            if (isRecord(action))
+                checkAction(action, `${here}[${index}]`, event, context);
+        });
+    }
+}
+/**
+ * One closed action: the fields its op takes, then its targets. At most one
+ * diagnostic per action (the first problem). `event` is the firing event,
+ * unknown for an action given as a prop value.
+ */
+function checkAction(action, path, event, context) {
+    const { state, flow, fail } = context;
+    const op = action.op;
+    if (!SPEC_ACTION_OPS.includes(op))
+        return;
+    const fields = ACTION_FIELDS[op];
+    // Unknown keys are the schema's to report; only fields of another op are judged here.
+    const extra = Object.keys(action).find((key) => ACTION_KEYS.has(key) && !fields.allowed.includes(key));
+    if (extra !== undefined) {
+        fail('action', `${path}.${extra}`, `${String(op)} takes no "${extra}".`);
+        return;
+    }
+    const missing = fields.required.find((key) => !Object.hasOwn(action, key));
+    if (missing !== undefined) {
+        fail('action', `${path}.${missing}`, `${String(op)} needs "${missing}".`);
+        return;
+    }
+    /** The declared variable `key` names, or null after reporting it. */
+    const variable = (key) => {
+        const name = action[key];
+        if (typeof name !== 'string')
+            return null;
+        const found = state.get(name);
+        if (!found) {
+            fail('unknown-state', `${path}.${key}`, `No state variable named "${name}".`);
+            return null;
+        }
+        // A refused declaration was reported once; judging its uses would only cascade.
+        if (!found.valid)
+            return null;
+        if (!found.writable) {
+            fail('action', `${path}.${key}`, `"${name}" is host-bound and read-only.`);
+            return null;
+        }
+        return found;
+    };
+    switch (op) {
+        case 'setState': {
+            const hasValue = Object.hasOwn(action, 'value');
+            if (hasValue === Object.hasOwn(action, 'fromEvent')) {
+                fail('action', path, 'setState takes exactly one of "value" and "fromEvent".');
+                return;
+            }
+            const target = variable('state');
+            if (!target)
+                return;
+            if (target.type === 'list' || target.type === 'workflow') {
+                fail('action', `${path}.state`, `setState cannot replace a ${target.type}; use moveItem.`);
+            }
+            else if (hasValue && target.valid && !fitsVariable(target, action.value)) {
+                fail('action', `${path}.value`, `The value does not fit "${String(action.state)}".`);
+            }
+            else if (!hasValue && event !== undefined && event !== 'change' && event !== 'select') {
+                fail('action', `${path}.fromEvent`, 'fromEvent reads the value of a change or select event.');
+            }
+            return;
+        }
+        case 'toggleState': {
+            const target = variable('state');
+            if (target && target.type !== 'boolean') {
+                fail('action', `${path}.state`, 'toggleState flips a boolean.');
+            }
+            return;
+        }
+        case 'moveItem': {
+            for (const key of ['from', 'to']) {
+                if (!Object.hasOwn(action, key))
+                    continue;
+                const target = variable(key);
+                if (!target)
+                    return;
+                if (target.type !== 'list') {
+                    fail('action', `${path}.${key}`, 'moveItem moves items between lists.');
+                    return;
+                }
+            }
+            return;
+        }
+        case 'flowGo': {
+            if (!flow)
+                fail('action', path, 'flowGo needs a declared flow.');
+            else if (!flow.events.has(action.event)) {
+                fail('action', `${path}.event`, `No transition handles "${String(action.event)}".`);
+            }
+            return;
+        }
+        case 'emit': {
+            if (!isRecord(action.values))
+                return;
+            const entries = Object.entries(action.values);
+            if (entries.length > SPEC_LIMITS.emitValues) {
+                fail('action', `${path}.values`, `At most ${SPEC_LIMITS.emitValues} values.`);
+                return;
+            }
+            for (const [name, value] of entries) {
+                const here = `${path}.values.${name}`;
+                if (!SPEC_REGEX.intentName.test(name)) {
+                    fail('action', here, `"${name}" is not a value name.`);
+                    return;
+                }
+                if (isRecord(value)) {
+                    const target = bindingTarget(value);
+                    if (!target || target.key !== STATE_BINDING_KEY) {
+                        fail('action', here, 'An emitted value is a scalar or {"$state": name}.');
+                        return;
+                    }
+                    const found = state.get(target.name);
+                    if (!found) {
+                        fail('unknown-state', here, `No state variable named "${target.name}".`);
+                        return;
+                    }
+                    if (found.valid && (found.type === 'list' || found.type === 'workflow')) {
+                        fail('action', here, 'Only scalar variables can be emitted.');
+                        return;
+                    }
+                }
+                else if (!(typeof value === 'boolean' ||
+                    finite(value) ||
+                    (typeof value === 'string' && value.length <= SPEC_LIMITS.emitValueLength))) {
+                    fail('action', here, 'An emitted value is a boolean, a number or a short string.');
+                    return;
+                }
+            }
+            return;
+        }
+        case 'submit': {
+            if (!context.insideForm)
+                fail('action', path, `submit runs only inside an ${FORM_ID}.`);
+            return;
+        }
+    }
+}
+/** Whether `value` is a legal value of a scalar variable. */
+function fitsVariable(variable, value) {
+    switch (variable.type) {
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'number':
+            return (finite(value) &&
+                value >= (variable.min ?? Number.NEGATIVE_INFINITY) &&
+                value <= (variable.max ?? Number.POSITIVE_INFINITY));
+        case 'enum':
+            return typeof value === 'string' && (variable.values ?? []).includes(value);
+        case 'string':
+            return typeof value === 'string' && value.length <= (variable.maxLength ?? 0);
+        default:
+            return false;
+    }
+}
+function finite(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}