@hatiolab/figure-model 0.6.4 → 0.6.6

package/dist/data-interface.js

@@ -0,0 +1,723 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ */
+/*
+ * A figure's data and what it moves inside the figure (ADR-0051 §8, data binding design appendix A).
+ *
+ * The author describes the data the figure takes in the site's own field names -- objects, lists, numbers, booleans,
+ * text -- and binds values of it to what the figure does: a state input, a colour, a motion group's clip, speed or
+ * pause, a status port, the instance's position, the items in its places. A binding has the board's mapping shape --
+ * an accessor into the data, a rule (`value`, `map`, `range`, `scale`) and its param -- so a person who binds data on a
+ * board binds it on a figure in the same words. The figure's bindings are its own: every board that places it moves it
+ * with the same data, and a board rarely binds more.
+ *
+ * This module checks the declaration once, when the asset is read: each accessor goes down the schema to what its
+ * behavior reads, and each rule's results are what the behavior takes over the whole of the value's domain. While the
+ * figure runs it checks the data against the schema -- a value of the wrong kind refuses the whole of it -- and gives
+ * each binding the value it reads. Turning that value into the behavior's input by the rule is things-scene's, the same
+ * evaluator a board mapping runs; nothing here holds time or an instance.
+ */
+import { FigureContractError } from "./contract.js";
+import { figureUnitKnown } from "./graph.js";
+import { FIGURE_PART_ID } from "./part-ids.js";
+/** The fastest a motion group plays: three times its authored speed. 0 stops it. */
+export const FIGURE_MOTION_SPEED_MAX = 3;
+const COLOUR = /^#[0-9a-f]{6}$/i;
+/** A field name as the board's accessor reads it bare: a letter or `_`, then letters, digits, `_` and `-`. Not `$`: the accessor reads that as a variable. */
+const FIELD_NAME = /^[A-Za-z_][\w-]*$/;
+const fail = (code, path, message, details) => {
+    throw new FigureContractError(code, path, message, details);
+};
+const refuse = (path, message, details) => fail('DATA_INTERFACE', path, message, details);
+function fields(o, required, optional, path) {
+    if (!o || typeof o !== 'object' || Array.isArray(o))
+        fail('ASSET_SCHEMA', path, 'object required');
+    for (const k of required)
+        if (!Object.hasOwn(o, k))
+            fail('ASSET_SCHEMA', path, `missing ${k}`);
+    for (const k of Object.keys(o))
+        if (![...required, ...optional].includes(k))
+            fail('ASSET_SCHEMA', path, `unknown ${k}`);
+}
+const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+/**
+ * An accessor read as steps, or null when it is not one this contract takes: field names joined by `.`, each followed
+ * by at most one `[n]`. The board's accessor (JSONata) reads these the same way; nothing richer is taken, because a
+ * richer expression cannot be followed down the schema.
+ */
+export function parseFigureAccessor(accessor) {
+    if (typeof accessor !== 'string' || !accessor)
+        return null;
+    const steps = [];
+    for (const part of accessor.split('.')) {
+        const m = /^([A-Za-z_][\w-]*)(?:\[(\d+)\])?$/.exec(part);
+        if (!m)
+            return null;
+        steps.push({ field: m[1] });
+        if (m[2] !== undefined)
+            steps.push({ index: Number(m[2]) });
+    }
+    return steps;
+}
+/** An accessor written back from its steps. */
+export const figureAccessorOf = (steps) => steps.map((s, i) => ('index' in s ? `[${s.index}]` : i ? `.${s.field}` : s.field)).join('');
+function nodeAt(schema, steps) {
+    let node = { kind: 'object', fields: schema };
+    let field;
+    for (const step of steps) {
+        if ('field' in step) {
+            if (node.kind !== 'object')
+                return { why: 'absent' };
+            const next = node.fields.find(f => f.name === step.field);
+            if (!next)
+                return { why: 'absent' };
+            node = next;
+            field = next;
+        }
+        else {
+            if (node.kind !== 'list')
+                return { why: 'not-a-list' };
+            node = node.item;
+            field = undefined;
+        }
+    }
+    return { node, ...(field ? { field } : {}) };
+}
+const isValue = (n) => n.kind === 'number' || n.kind === 'boolean' || n.kind === 'text';
+/* ---------------------------------------------------------------- the schema */
+function checkNode(n, path, named) {
+    if (!n || typeof n !== 'object' || Array.isArray(n))
+        fail('ASSET_SCHEMA', path, 'object required');
+    const head = named ? ['name', 'label', 'json'] : [];
+    const kind = n.kind;
+    const invalid = (what, message) => refuse(`${path}.${what}`, message, { reason: 'data-field-invalid', field: path, what });
+    if (kind === 'object')
+        fields(n, ['kind', 'fields'], head, path);
+    else if (kind === 'list')
+        fields(n, ['kind', 'item'], head, path);
+    else if (kind === 'number')
+        fields(n, ['kind'], [...head, 'unit', 'min', 'max', 'default'], path);
+    else if (kind === 'boolean')
+        fields(n, ['kind'], [...head, 'default'], path);
+    else if (kind === 'text')
+        fields(n, ['kind'], [...head, 'values', 'default'], path);
+    else
+        fail('ASSET_SCHEMA', `${path}.kind`, `${String(kind)} is not a data kind; object, list, number, boolean or text`);
+    if (named) {
+        if (typeof n.name !== 'string' || !FIELD_NAME.test(n.name))
+            invalid('name', `${String(n.name)} is not a field name: a letter or _, then letters, digits, _ and -`);
+        if (n.label !== undefined && (typeof n.label !== 'string' || !n.label.trim()))
+            invalid('label', 'a name shown to a person, or none');
+        if (n.json !== undefined && (n.json !== true || (kind !== 'object' && kind !== 'list')))
+            invalid('json', 'only an object or a list may come as JSON text');
+    }
+    if (kind === 'object') {
+        if (!Array.isArray(n.fields))
+            fail('ASSET_SCHEMA', `${path}.fields`, 'a list of fields');
+        checkFields(n.fields, `${path}.fields`);
+    }
+    else if (kind === 'list')
+        checkNode(n.item, `${path}.item`, false);
+    else if (kind === 'number') {
+        if (n.unit !== undefined && !figureUnitKnown(n.unit))
+            invalid('unit', `${String(n.unit)} is not a unit`);
+        for (const k of ['min', 'max', 'default'])
+            if (n[k] !== undefined && !finite(n[k]))
+                invalid(k, 'a finite number');
+        if (n.min !== undefined && n.max !== undefined && !(n.min <= n.max))
+            invalid('min', 'a range from a number to one no smaller');
+        if (n.default !== undefined && ((n.min !== undefined && n.default < n.min) || (n.max !== undefined && n.default > n.max)))
+            invalid('default', 'the default lies in the range');
+    }
+    else if (kind === 'boolean') {
+        if (n.default !== undefined && typeof n.default !== 'boolean')
+            invalid('default', 'true or false');
+    }
+    else {
+        if (n.values !== undefined) {
+            if (!Array.isArray(n.values) || !n.values.length || n.values.some((v) => typeof v !== 'string' || !v))
+                invalid('values', 'one or more nonempty strings');
+            if (new Set(n.values).size !== n.values.length)
+                invalid('values', 'each value once');
+        }
+        if (n.default !== undefined) {
+            if (typeof n.default !== 'string')
+                invalid('default', 'a string');
+            if (n.values && !n.values.includes(n.default))
+                invalid('default', 'the default is one of the values');
+        }
+    }
+}
+function checkFields(list, path) {
+    const names = new Set();
+    list.forEach((f, i) => {
+        checkNode(f, `${path}[${i}]`, true);
+        if (names.has(f.name))
+            refuse(`${path}[${i}].name`, `${f.name} is a field twice`, { reason: 'data-field-duplicate', field: `${path}[${i}]`, name: f.name });
+        names.add(f.name);
+    });
+}
+const targetsOf = (asset) => ({
+    states: new Map(asset.document.model.inputs.filter(i => i.role === 'state').map(i => [i.id, i])),
+    palette: asset.palette,
+    groups: new Map((asset.motionGroups ?? []).map(g => [g.id, g.clips])),
+    ports: new Map((asset.dataInterface?.ports ?? []).map(p => [p.id, p])),
+    parts: new Set(asset.appearance.map(a => a.target))
+});
+/** The one thing a binding writes, as a key no other binding may hold. Items are stacked, so several may fill them. */
+const writeKey = (b) => b.kind === 'state' ? `state ${b.input}` : b.kind === 'palette' ? `palette ${b.token}` : b.kind === 'status' ? `status ${b.port}` : b.kind === 'pose' ? `pose ${b.axis}` : b.kind === 'items' ? null : `${b.kind} ${b.group}`;
+const behaviorId = (b) => b.kind === 'state' ? b.input : b.kind === 'palette' ? b.token : b.kind === 'status' ? b.port : b.kind === 'pose' ? b.axis : b.kind === 'items' ? (b.slot ?? '') : b.group;
+function checkBehavior(b, path) {
+    if (!b || typeof b !== 'object' || Array.isArray(b))
+        fail('ASSET_SCHEMA', path, 'object required');
+    const k = b.kind;
+    if (k === 'state')
+        fields(b, ['kind', 'input', 'sourceMode'], [], path);
+    else if (k === 'palette')
+        fields(b, ['kind', 'token'], [], path);
+    else if (k === 'motion-clip' || k === 'motion-speed' || k === 'motion-paused')
+        fields(b, ['kind', 'group'], [], path);
+    else if (k === 'status')
+        fields(b, ['kind', 'port'], [], path);
+    else if (k === 'pose')
+        fields(b, ['kind', 'axis'], ['seconds'], path);
+    else if (k === 'items')
+        fields(b, ['kind'], ['slot', 'id', 'type', 'place', 'stack', 'status'], path);
+    else
+        fail('ASSET_SCHEMA', `${path}.kind`, `${String(k)} is not a behavior; state, palette, motion-clip, motion-speed, motion-paused, status, pose or items`);
+    if (k === 'state' && b.sourceMode !== 'observed' && b.sourceMode !== 'commanded')
+        fail('ASSET_SCHEMA', `${path}.sourceMode`, 'observed or commanded');
+    if (k === 'pose' && !['x', 'y', 'z', 'heading'].includes(b.axis))
+        fail('ASSET_SCHEMA', `${path}.axis`, 'x, y, z or heading');
+    if (k === 'pose' && b.seconds !== undefined && !(finite(b.seconds) && b.seconds >= 0))
+        fail('ASSET_SCHEMA', `${path}.seconds`, 'seconds from 0');
+    for (const f of ['input', 'token', 'group', 'port', 'slot', 'id', 'type', 'place', 'stack', 'status'])
+        if (Object.hasOwn(b, f) && (typeof b[f] !== 'string' || !b[f]))
+            fail('ASSET_SCHEMA', `${path}.${f}`, 'a nonempty string');
+    return b;
+}
+/** The values a value node takes, when they are few: a closed text's values, both booleans. Null when open. */
+function closedDomain(node) {
+    if (node.kind === 'boolean')
+        return [false, true];
+    if (node.kind === 'text' && node.values)
+        return node.values;
+    return null;
+}
+/** One interval of a `range` param, as the board's evaluator reads its key: `from~to`, either end left open. */
+function intervalOf(key) {
+    const parts = key.split('~');
+    if (parts.length !== 2)
+        return null;
+    const [a, b] = parts;
+    const from = a === '' ? -Infinity : Number(a);
+    const to = b === '' ? Infinity : Number(b);
+    if ((a !== '' && !finite(from)) || (b !== '' && !finite(to)) || !(from < to))
+        return null;
+    return [from, to];
+}
+/**
+ * Whether a binding's results are what its behavior takes, over the whole of what the value can be (the detail design's
+ * check, kept): a number's range, every closed value, both booleans -- never a sample.
+ */
+function checkRule(b, node, targets, path) {
+    const domain = (why, message, extra = {}) => refuse(path, message, { reason: 'data-rule-domain', binding: b.id, why, ...extra });
+    const behavior = b.behavior;
+    /* Is the result one the behavior takes? */
+    const output = (value) => {
+        if (behavior.kind === 'state') {
+            const input = targets.states.get(behavior.input);
+            if (!finite(value))
+                return domain('output', `a state input takes a number in ${input.unit}`, { value });
+            if (value < input.min || value > input.max)
+                domain('output', `${value} is outside ${behavior.input}, ${input.min} to ${input.max}`, { value, within: [input.min, input.max] });
+        }
+        else if (behavior.kind === 'palette') {
+            if (typeof value !== 'string' || !COLOUR.test(value))
+                domain('output', 'a colour is #RRGGBB', { value });
+        }
+        else if (behavior.kind === 'motion-clip') {
+            if (typeof value !== 'string' || !targets.groups.get(behavior.group).includes(value))
+                domain('output', `${String(value)} is not a clip of ${behavior.group}`, { value });
+        }
+        else if (behavior.kind === 'motion-speed') {
+            if (!finite(value) || value < 0 || value > FIGURE_MOTION_SPEED_MAX)
+                domain('output', `a motion speed is 0 to ${FIGURE_MOTION_SPEED_MAX}`, { value });
+        }
+        else if (behavior.kind === 'motion-paused') {
+            if (typeof value !== 'boolean')
+                domain('output', 'a pause is true or false', { value });
+        }
+        else if (behavior.kind === 'status') {
+            if (typeof value !== 'string' && !finite(value))
+                domain('output', 'a status is a code', { value });
+        }
+        else if (behavior.kind === 'pose') {
+            if (!finite(value))
+                domain('output', 'a position is a number', { value });
+        }
+    };
+    const param = b.param;
+    if (behavior.kind === 'items') {
+        if (b.rule !== 'value' || param !== undefined)
+            domain('kind', 'items are read as they are: rule value, no param');
+        return;
+    }
+    if (!isValue(node))
+        return domain('kind', `${b.accessor} is ${node.kind === 'list' ? 'a list' : 'an object'}; this behavior reads one value`);
+    if (b.rule === 'map') {
+        if (!param || typeof param !== 'object')
+            return domain('cases', 'a map gives a result for each value: { value: result, default }');
+        const closed = closedDomain(node);
+        const keys = Object.keys(param).filter(k => k !== 'default');
+        if (closed)
+            for (const k of keys)
+                if (!closed.some(v => String(v) === k))
+                    domain('cases', `${k} is not a value of ${b.accessor}`, { value: k });
+        const covered = closed ? closed.every(v => Object.hasOwn(param, String(v))) : false;
+        if (!covered && !Object.hasOwn(param, 'default'))
+            domain('default', closed ? `not every value of ${b.accessor} has a result; give a default` : `${b.accessor} is open; give a default`);
+        for (const k of Object.keys(param))
+            output(param[k]);
+        return;
+    }
+    if (b.rule === 'range') {
+        if (node.kind !== 'number')
+            return domain('kind', `a range reads a number; ${b.accessor} is ${node.kind}`);
+        if (!param || typeof param !== 'object')
+            return domain('cases', "a range gives a result for each interval: { 'from~to': result, default }");
+        const intervals = [];
+        for (const k of Object.keys(param)) {
+            if (k === 'default')
+                continue;
+            const iv = intervalOf(k);
+            if (!iv)
+                domain('cases', `${k} is not an interval: from~to, either end may be left out`, { value: k });
+            intervals.push(iv);
+        }
+        if (!Object.hasOwn(param, 'default') && !covers(intervals, node.min ?? -Infinity, node.max ?? Infinity))
+            domain('default', `the intervals leave values of ${b.accessor} without a result; give a default`);
+        for (const k of Object.keys(param))
+            output(param[k]);
+        return;
+    }
+    if (b.rule !== 'value' && b.rule !== 'scale')
+        return domain('kind', `${String(b.rule)} is not a rule; value, map, range or scale`);
+    /* value and scale: the value itself, or scale × value + offset. */
+    let scale = 1;
+    let offset = 0;
+    if (b.rule === 'scale') {
+        if (!param || !finite(param.scale) || !finite(param.offset) || Object.keys(param).some(k => k !== 'scale' && k !== 'offset'))
+            return domain('cases', 'a scale is { scale, offset }, two finite numbers');
+        if (node.kind !== 'number')
+            return domain('kind', `a scale reads a number; ${b.accessor} is ${node.kind}`);
+        scale = param.scale;
+        offset = param.offset;
+    }
+    else if (param !== undefined)
+        return domain('cases', 'value takes no param');
+    if (behavior.kind === 'status') {
+        if (b.rule === 'scale')
+            domain('kind', 'a status is a code; it is read as it is or by a map');
+        if (node.kind === 'boolean')
+            domain('kind', 'a status is a code: a number or a text');
+        return;
+    }
+    if (behavior.kind === 'motion-clip' || behavior.kind === 'palette') {
+        if (b.rule === 'scale' || node.kind !== 'text' || !node.values)
+            return domain('kind', `${behavior.kind === 'palette' ? 'a colour' : 'a clip'} is read as it is only from a text of fixed values; otherwise by a map`);
+        for (const v of node.values)
+            output(v);
+        return;
+    }
+    if (behavior.kind === 'motion-paused') {
+        if (b.rule === 'scale' || node.kind !== 'boolean')
+            domain('kind', 'a pause is read as it is only from true or false; otherwise by a map');
+        return;
+    }
+    /* state, motion-speed and pose read a number. */
+    if (node.kind !== 'number')
+        return domain('kind', `${b.accessor} is ${node.kind === 'text' ? 'a text' : 'true or false'}; this behavior reads a number, or a value by a map`);
+    if (behavior.kind === 'pose') {
+        const unit = behavior.axis === 'heading' ? 'deg' : 'mm';
+        if (b.rule === 'value' && node.unit !== unit)
+            domain('unit', `${b.accessor} is in ${node.unit ?? 'no unit'}; a ${behavior.axis === 'heading' ? 'heading' : 'position'} is in ${unit}; say the unit, or scale it`, { from: node.unit ?? '', to: unit });
+        return;
+    }
+    if (behavior.kind === 'motion-speed') {
+        if (b.rule === 'value' && node.unit !== undefined && node.unit !== 'ratio')
+            domain('unit', `a motion speed is a ratio; ${b.accessor} is in ${node.unit}`, { from: node.unit, to: 'ratio' });
+    }
+    else {
+        const input = targets.states.get(behavior.input);
+        /* As it is, only in the same unit: no unit is guessed. Another unit is a scale the author writes. */
+        if (b.rule === 'value' && node.unit !== input.unit)
+            domain('unit', `${b.accessor} is in ${node.unit ?? 'no unit'} and ${behavior.input} in ${input.unit}; say how one becomes the other`, { from: node.unit ?? '', to: input.unit });
+    }
+    const [lo, hi] = behavior.kind === 'motion-speed' ? [0, FIGURE_MOTION_SPEED_MAX] : [targets.states.get(behavior.input).min, targets.states.get(behavior.input).max];
+    if (node.min === undefined || node.max === undefined)
+        return domain('range', `${b.accessor} has no range; give it one inside ${lo} to ${hi}`, { within: [lo, hi] });
+    const ends = [scale * node.min + offset, scale * node.max + offset].sort((x, y) => x - y);
+    if (ends[0] < lo || ends[1] > hi)
+        domain('range', `${b.accessor} gives ${ends[0]} to ${ends[1]}; ${behaviorId(behavior)} takes ${lo} to ${hi}`, { min: ends[0], max: ends[1], within: [lo, hi] });
+}
+/** Whether intervals `from <= v < to` (the board evaluator's reading) leave no value from min to max, both included, without one. */
+function covers(intervals, min, max) {
+    let at = min;
+    for (const [from, to] of [...intervals].sort((a, b) => a[0] - b[0])) {
+        if (from > at)
+            return false;
+        if (to > at)
+            at = to;
+        if (at === Infinity || at > max)
+            return true;
+    }
+    return false;
+}
+function checkBinding(b, schema, targets, path) {
+    fields(b, ['id', 'accessor', 'behavior', 'rule'], ['param'], path);
+    if (typeof b.id !== 'string' || !FIGURE_PART_ID.test(b.id))
+        refuse(`${path}.id`, `${String(b.id)} is not an id: a letter, then letters, digits, - and _`, { reason: 'data-id-invalid', list: 'bindings', id: String(b.id) });
+    const behavior = checkBehavior(b.behavior, `${path}.behavior`);
+    if (b.param !== undefined && (!b.param || typeof b.param !== 'object' || Array.isArray(b.param)))
+        fail('ASSET_SCHEMA', `${path}.param`, 'an object of results');
+    /* The behavior is there. */
+    const absent = (id) => refuse(`${path}.behavior`, `${id} is not a ${behavior.kind} of this figure`, { reason: 'data-behavior-absent', binding: b.id, behavior: behavior.kind, id });
+    if (behavior.kind === 'state' && !targets.states.has(behavior.input))
+        absent(behavior.input);
+    if (behavior.kind === 'palette' && !Object.hasOwn(targets.palette, behavior.token))
+        absent(behavior.token);
+    if ((behavior.kind === 'motion-clip' || behavior.kind === 'motion-speed' || behavior.kind === 'motion-paused') && !targets.groups.has(behavior.group))
+        absent(behavior.group);
+    if (behavior.kind === 'status' && !targets.ports.has(behavior.port))
+        absent(behavior.port);
+    /* The accessor goes down the schema to what the behavior reads. */
+    const accessorRefused = (accessor, why) => refuse(`${path}.accessor`, `${accessor}: ${why}`, { reason: 'data-accessor-invalid', binding: b.id, accessor, why });
+    const steps = parseFigureAccessor(b.accessor);
+    if (!steps)
+        accessorRefused(String(b.accessor), 'syntax');
+    const found = nodeAt(schema, steps);
+    if ('why' in found)
+        return accessorRefused(b.accessor, found.why);
+    if (behavior.kind === 'items') {
+        if (found.node.kind === 'list') {
+            const item = found.node.item;
+            if (!behavior.id)
+                refuse(`${path}.behavior.id`, 'items from a list say which field of an element is its id', { reason: 'data-accessor-invalid', binding: b.id, accessor: b.accessor, why: 'item-id-required' });
+            for (const f of ['id', 'type', 'place', 'stack', 'status']) {
+                const rel = behavior[f];
+                if (rel === undefined)
+                    continue;
+                const relSteps = parseFigureAccessor(rel);
+                if (!relSteps)
+                    accessorRefused(rel, 'syntax');
+                const at = nodeAt(item.kind === 'object' ? item.fields : [], relSteps);
+                if ('why' in at)
+                    accessorRefused(`${b.accessor}[].${rel}`, at.why);
+                else if (!isValue(at.node))
+                    accessorRefused(`${b.accessor}[].${rel}`, 'not-a-value');
+            }
+        }
+        else if (isValue(found.node)) {
+            if (behavior.id || behavior.type || behavior.place || behavior.stack || behavior.status)
+                refuse(`${path}.behavior`, 'one value is the id itself; element fields are for a list', { reason: 'data-accessor-invalid', binding: b.id, accessor: b.accessor, why: 'not-a-list' });
+        }
+        else
+            accessorRefused(b.accessor, 'not-a-value');
+    }
+    else if (found.node.kind === 'list')
+        accessorRefused(b.accessor, 'list-needs-index');
+    else if (!isValue(found.node))
+        accessorRefused(b.accessor, 'not-a-value');
+    checkRule(b, found.node, targets, path);
+    return b;
+}
+function checkPort(p, targets, path) {
+    fields(p, ['id', 'label', 'tokens', 'parts'], ['group'], path);
+    if (typeof p.id !== 'string' || !FIGURE_PART_ID.test(p.id))
+        refuse(`${path}.id`, `${String(p.id)} is not an id: a letter, then letters, digits, - and _`, { reason: 'data-id-invalid', list: 'ports', id: String(p.id) });
+    const invalid = (what, message, id) => refuse(`${path}.${what}`, message, { reason: 'data-port-invalid', port: p.id, what, ...(id !== undefined ? { id } : {}) });
+    if (typeof p.label !== 'string' || !p.label.trim())
+        invalid('label', 'a name shown to a person');
+    if (!Array.isArray(p.tokens) || !Array.isArray(p.parts))
+        fail('ASSET_SCHEMA', path, 'tokens and parts are lists');
+    if (!p.tokens.length && !p.parts.length)
+        invalid('token', 'a status port shows on a colour token, a part, or both');
+    for (const t of p.tokens)
+        if (typeof t !== 'string' || !Object.hasOwn(targets.palette, t))
+            invalid('token', `${String(t)} is not a colour of this figure`, String(t));
+    for (const part of p.parts)
+        if (typeof part !== 'string' || !targets.parts.has(part))
+            invalid('part', `${String(part)} is not a part of this figure`, String(part));
+    if (p.group !== undefined && (typeof p.group !== 'string' || !targets.groups.has(p.group)))
+        invalid('group', `${String(p.group)} is not a motion group of this figure`, String(p.group));
+    return p;
+}
+/**
+ * Refuses a data interface the contract does not allow (`DATA_INTERFACE`, or `ASSET_SCHEMA` for its shape). Called by
+ * `compileFigureAsset`, after the drivers and motion groups, whose clips a binding may name.
+ */
+export function validateFigureDataInterface(asset) {
+    const di = asset.dataInterface;
+    if (di === undefined)
+        return;
+    fields(di, ['version', 'schema', 'bindings'], ['ports'], 'dataInterface');
+    if (di.version !== 'figure-data-interface-2')
+        fail('VERSION', 'dataInterface.version', String(di.version));
+    if (!Array.isArray(di.schema))
+        fail('ASSET_SCHEMA', 'dataInterface.schema', 'a list of fields');
+    if (!Array.isArray(di.bindings))
+        fail('ASSET_SCHEMA', 'dataInterface.bindings', 'a list of bindings');
+    if (di.ports !== undefined && !Array.isArray(di.ports))
+        fail('ASSET_SCHEMA', 'dataInterface.ports', 'a list of status ports');
+    checkFields(di.schema, 'dataInterface.schema');
+    const targets = targetsOf(asset);
+    const portIds = new Set();
+    (di.ports ?? []).forEach((p, i) => {
+        const port = checkPort(p, targets, `dataInterface.ports[${i}]`);
+        if (portIds.has(port.id))
+            refuse(`dataInterface.ports[${i}].id`, `${port.id} is declared twice`, { reason: 'data-id-duplicate', list: 'ports', id: port.id });
+        portIds.add(port.id);
+    });
+    const ids = new Set();
+    const writers = new Map();
+    di.bindings.forEach((b, i) => {
+        const path = `dataInterface.bindings[${i}]`;
+        const binding = checkBinding(b, di.schema, targets, path);
+        if (ids.has(binding.id))
+            refuse(`${path}.id`, `${binding.id} is declared twice`, { reason: 'data-id-duplicate', list: 'bindings', id: binding.id });
+        ids.add(binding.id);
+        const key = writeKey(binding.behavior);
+        if (key === null)
+            return;
+        const other = writers.get(key);
+        if (other !== undefined)
+            refuse(`${path}.behavior`, `${other} and ${binding.id} both write ${key}; one writer each`, {
+                reason: 'data-behavior-duplicate',
+                bindings: [other, binding.id],
+                behavior: binding.behavior.kind,
+                id: behaviorId(binding.behavior)
+            });
+        writers.set(key, binding.id);
+    });
+}
+/** The data interface of an asset, checked, with what the schema has at each binding; null when the figure declares none. */
+export function compileFigureDataInterface(asset) {
+    if (asset.dataInterface === undefined)
+        return null;
+    validateFigureDataInterface(asset);
+    const di = structuredClone(asset.dataInterface);
+    const bindings = di.bindings.map(binding => {
+        const node = nodeAt(di.schema, parseFigureAccessor(binding.accessor)).node;
+        let itemNodes;
+        if (binding.behavior.kind === 'items' && node.kind === 'list') {
+            const item = node.item;
+            itemNodes = {};
+            for (const role of ['id', 'type', 'place', 'stack', 'status']) {
+                const rel = binding.behavior[role];
+                if (rel)
+                    itemNodes[role] = nodeAt(item.kind === 'object' ? item.fields : [], parseFigureAccessor(rel)).node;
+            }
+        }
+        return Object.freeze({ binding: Object.freeze(binding), node, ...(itemNodes ? { itemNodes: Object.freeze(itemNodes) } : {}) });
+    });
+    const jsonFields = [];
+    const walk = (list, prefix) => {
+        for (const f of list) {
+            const at = prefix ? `${prefix}.${f.name}` : f.name;
+            if (f.json)
+                jsonFields.push(at);
+            let node = f;
+            let path = at;
+            while (node.kind === 'list') {
+                path = `${path}[]`;
+                node = node.item;
+            }
+            if (node.kind === 'object')
+                walk(node.fields, path);
+        }
+    };
+    walk(di.schema, '');
+    return Object.freeze({ schema: Object.freeze(di.schema), ports: Object.freeze(di.ports ?? []), bindings: Object.freeze(bindings), jsonFields: Object.freeze(jsonFields) });
+}
+/** The schema as lines, parents before their fields, with the bindings that read each place. */
+export function figureDataRows(di) {
+    const rows = [];
+    /* Every place a binding reads, as a row path: an accessor's indices read as `[]`, an item field under its list. */
+    const readers = new Map();
+    const note = (path, id) => readers.set(path, [...(readers.get(path) ?? []), id]);
+    const asRow = (accessor) => accessor.replace(/\[\d+\]/g, '[]');
+    for (const b of di.bindings) {
+        note(asRow(b.accessor), b.id);
+        if (b.behavior.kind === 'items')
+            for (const rel of [b.behavior.id, b.behavior.type, b.behavior.place, b.behavior.stack, b.behavior.status])
+                if (rel)
+                    note(`${asRow(b.accessor)}[].${asRow(rel)}`, b.id);
+    }
+    const walk = (list, prefix, depth) => {
+        for (const f of list) {
+            const path = prefix ? `${prefix}.${f.name}` : f.name;
+            rows.push({ path, depth, name: f.name, ...(f.label ? { label: f.label } : {}), node: f, json: !!f.json, bindings: readers.get(path) ?? [] });
+            let node = f;
+            let at = path;
+            while (node.kind === 'list') {
+                at = `${at}[]`;
+                node = node.item;
+            }
+            if (node.kind === 'object')
+                walk(node.fields, at, depth + 1);
+        }
+    };
+    walk(di.schema, '', 0);
+    return rows;
+}
+/** A value for a node, for an example: its default, else what it may take first. */
+function exampleOf(node) {
+    if (node.kind === 'object')
+        return Object.fromEntries(node.fields.map(f => [f.name, exampleOf(f)]));
+    if (node.kind === 'list')
+        return [exampleOf(node.item)];
+    if (node.kind === 'number')
+        return node.default ?? (node.min !== undefined && node.max !== undefined ? node.min : node.min ?? node.max ?? 0);
+    if (node.kind === 'boolean')
+        return node.default ?? false;
+    return node.default ?? node.values?.[0] ?? '';
+}
+/** Data with every field of the schema, each at its default or a value it takes: what a person copies and changes. */
+export function figureDataExample(di) {
+    return exampleOf({ kind: 'object', fields: di.schema });
+}
+/** A node guessed from one value of a sample. */
+function inferNode(value) {
+    if (typeof value === 'string') {
+        const t = value.trim();
+        if ((t.startsWith('[') && t.endsWith(']')) || (t.startsWith('{') && t.endsWith('}'))) {
+            try {
+                const parsed = JSON.parse(t);
+                if (parsed && typeof parsed === 'object')
+                    return { node: inferNode(parsed).node, json: true };
+            }
+            catch {
+                /* a text that only looks like JSON */
+            }
+        }
+        return { node: { kind: 'text' } };
+    }
+    if (typeof value === 'number')
+        return { node: { kind: 'number' } };
+    if (typeof value === 'boolean')
+        return { node: { kind: 'boolean' } };
+    if (Array.isArray(value)) {
+        /* Every element's fields, so a field only some elements carry is not lost. */
+        const objects = value.filter(v => v && typeof v === 'object' && !Array.isArray(v));
+        if (objects.length)
+            return { node: { kind: 'list', item: { kind: 'object', fields: inferFields(Object.assign({}, ...objects)) } } };
+        return { node: { kind: 'list', item: value.length ? inferNode(value[0]).node : { kind: 'text' } } };
+    }
+    if (value && typeof value === 'object')
+        return { node: { kind: 'object', fields: inferFields(value) } };
+    return { node: { kind: 'text' } };
+}
+function inferFields(sample) {
+    return Object.keys(sample)
+        .filter(k => FIELD_NAME.test(k))
+        .map(k => {
+        const { node, json } = inferNode(sample[k]);
+        return { name: k, ...node, ...(json ? { json } : {}) };
+    });
+}
+/**
+ * A schema guessed from one piece of a site's data: each field's kind as it came, a JSON text read as what it holds.
+ * Units, ranges and fixed values are not guessed -- a person says them. A field name the accessor cannot read bare is
+ * left out.
+ */
+export function inferFigureDataSchema(sample) {
+    if (!sample || typeof sample !== 'object' || Array.isArray(sample))
+        return [];
+    return inferFields(sample);
+}
+/* ---------------------------------------------------------------- renames */
+/** The interface after a part was renamed: a state input the part owned (`<part>.…`) and a status port's part follow it. */
+export function renameDataInterface(asset, from, to) {
+    if (!asset.dataInterface)
+        return;
+    const moved = (id) => (id === from ? to : id.startsWith(`${from}.`) ? to + id.slice(from.length) : id);
+    asset.dataInterface = {
+        ...asset.dataInterface,
+        ...(asset.dataInterface.ports ? { ports: asset.dataInterface.ports.map(p => ({ ...p, parts: p.parts.map(moved) })) } : {}),
+        bindings: asset.dataInterface.bindings.map(b => (b.behavior.kind === 'state' ? { ...b, behavior: { ...b.behavior, input: moved(b.behavior.input) } } : b))
+    };
+}
+/** The interface after a clip was renamed: every map that selects it in a motion group selects it by its new name. */
+export function renameDataInterfaceClip(asset, group, from, to) {
+    if (!asset.dataInterface)
+        return;
+    asset.dataInterface = {
+        ...asset.dataInterface,
+        bindings: asset.dataInterface.bindings.map(b => b.behavior.kind === 'motion-clip' && b.behavior.group === group && b.param && (b.rule === 'map' || b.rule === 'range')
+            ? { ...b, param: Object.fromEntries(Object.entries(b.param).map(([k, v]) => [k, v === from ? to : v])) }
+            : b)
+    };
+}
+/**
+ * The interface after a field was renamed: the field, and every accessor that goes through it, including an items
+ * binding's element fields. `accessor` names the field by its field names (no list indices); `to` is its new name.
+ */
+export function renameDataField(di, accessor, to) {
+    const steps = parseFigureAccessor(accessor);
+    if (!steps || steps.some(s => 'index' in s))
+        return fail('TARGET_ABSENT', accessor, `${accessor} does not name a field`);
+    if (typeof to !== 'string' || !FIELD_NAME.test(to))
+        refuse('to', `${String(to)} is not a field name`, { reason: 'data-field-invalid', field: accessor, what: 'name' });
+    const names = steps.map(s => s.field);
+    const out = structuredClone(di);
+    /* The field itself, down the schema through objects and lists. */
+    let list = out.schema;
+    names.forEach((name, i) => {
+        const f = list.find(x => x.name === name);
+        if (!f)
+            fail('TARGET_ABSENT', accessor, `${accessor} is not a field of this schema`);
+        if (i === names.length - 1) {
+            if (to !== name && list.some(x => x.name === to))
+                refuse('to', `${to} is a field already`, { reason: 'data-field-duplicate', field: accessor, name: to });
+            f.name = to;
+            return;
+        }
+        let node = f;
+        while (node.kind === 'list')
+            node = node.item;
+        if (node.kind !== 'object')
+            fail('TARGET_ABSENT', accessor, `${accessor} is not a field of this schema`);
+        list = node.fields;
+    });
+    /*
+      An accessor goes through the field when its field names, after `outer` (the list an element field sits in), start
+      with the renamed field's names. Its indices stay where they are.
+    */
+    const through = (acc, outer = []) => {
+        const s = parseFigureAccessor(acc);
+        if (!s)
+            return acc;
+        let n = outer.length;
+        return figureAccessorOf(s.map(step => {
+            if ('index' in step)
+                return step;
+            const at = n++;
+            const prefix = [...outer, ...s.filter(x => 'field' in x).map(x => x.field)];
+            return at === names.length - 1 && names.every((name, i) => prefix[i] === name) ? { field: to } : step;
+        }));
+    };
+    out.bindings = out.bindings.map(b => {
+        const next = { ...b, accessor: through(b.accessor) };
+        if (b.behavior.kind !== 'items')
+            return next;
+        const outer = (parseFigureAccessor(b.accessor) ?? []).filter(x => 'field' in x).map(x => x.field);
+        const behavior = { ...b.behavior };
+        for (const role of ['id', 'type', 'place', 'stack', 'status'])
+            if (behavior[role])
+                behavior[role] = through(behavior[role], outer);
+        return { ...next, behavior };
+    });
+    return out;
+}
+//# sourceMappingURL=data-interface.js.map