@hatiolab/figure-model 0.11.1 → 0.12.0

package/dist/data-interface.js

@@ -5,14 +5,16 @@
  * 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.
+ * text -- and binds values of it to what the figure does. A binding has the board's mapping shape -- an accessor into
+ * the data, a rule and what the rule needs -- so a person who binds data on a board binds it on a figure in the same
+ * words. One binding, three rules (ADR-0166): the value as it is or scaled moves one behavior (a state input, a colour,
+ * a motion group's clip, speed or pause, the instance's position, the items in its places); a table gives one look per
+ * code or per interval to several targets at once -- parts' colour and effect, state inputs' values, a motion group.
+ * The figure's bindings are its own: every board that places it moves it with the same data, and a board rarely binds
+ * more. A table a consumer may swap for a legend says so by a role; the legend is the consumer's.
  *
  * 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
+ * behavior reads, and each rule's results are what its targets take 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.
@@ -161,12 +163,32 @@ 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;
+/** The one thing a value 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 === '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 === 'pose' ? b.axis : b.kind === 'items' ? (b.slot ?? '') : b.group;
+/** The columns of a table's looks that set a motion group, with the behavior that sets the same in a value binding. */
+const GROUP_COLUMNS = [
+    ['clip', 'motion-clip'],
+    ['speed', 'motion-speed'],
+    ['paused', 'motion-paused']
+];
+/**
+ * What a table binding writes, under the keys a value binding's behavior holds (ADR-0166 6): each of its state inputs,
+ * and each of its group's clip, speed and pause a look sets. A part's colour and effect are no one binding's alone.
+ */
+function tableWrites(b) {
+    const out = (b.targets.inputs ?? []).map(input => ({ key: `state ${input}`, behavior: 'state', id: input }));
+    const group = b.targets.group;
+    if (group !== undefined) {
+        const looks = Object.values(b.table);
+        for (const [column, behavior] of GROUP_COLUMNS)
+            if (looks.some(look => look[column] !== undefined))
+                out.push({ key: `${behavior} ${group}`, behavior, id: group });
+    }
+    return out;
+}
 function checkBehavior(b, path) {
     if (!b || typeof b !== 'object' || Array.isArray(b))
         fail('ASSET_SCHEMA', path, 'object required');
@@ -177,21 +199,19 @@ function checkBehavior(b, path) {
         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`);
+        fail('ASSET_SCHEMA', `${path}.kind`, `${String(k)} is not a behavior; state, palette, motion-clip, motion-speed, motion-paused, 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'])
+    for (const f of ['input', 'token', 'group', '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;
@@ -204,8 +224,8 @@ function closedDomain(node) {
         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) {
+/** One interval of a range table, as the board's evaluator reads its key: `from~to`, either end left open. */
+export function figureIntervalOf(key) {
     const parts = key.split('~');
     if (parts.length !== 2)
         return null;
@@ -216,47 +236,14 @@ function intervalOf(key) {
         return null;
     return [from, to];
 }
+const domainOf = (id, path) => (why, message, extra = {}) => refuse(path, message, { reason: 'data-rule-domain', binding: id, why, ...extra });
 /**
- * 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.
+ * Whether a value 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 domain = domainOf(b.id, path);
     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 (!isFigureColour(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)
@@ -265,44 +252,8 @@ function checkRule(b, node, targets, path) {
     }
     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`);
+        return domain('kind', `${String(b.rule)} is not a rule; value, scale or table`);
     /* value and scale: the value itself, or scale × value + offset. */
     let scale = 1;
     let offset = 0;
@@ -316,28 +267,25 @@ function checkRule(b, node, targets, path) {
     }
     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 domain('kind', `${behavior.kind === 'palette' ? 'a colour' : 'a clip'} is read as it is only from a text of fixed values; otherwise by a table`);
+        for (const v of node.values) {
+            if (behavior.kind === 'palette' && !isFigureColour(v))
+                domain('output', 'a colour is #RRGGBB', { value: v });
+            if (behavior.kind === 'motion-clip' && !targets.groups.get(behavior.group).includes(v))
+                domain('output', `${v} is not a clip of ${behavior.group}`, { value: 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');
+            domain('kind', 'a pause is read as it is only from true or false; otherwise by a table');
         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`);
+        return domain('kind', `${b.accessor} is ${node.kind === 'text' ? 'a text' : 'true or false'}; this behavior reads a number, or a value by a table`);
     if (behavior.kind === 'pose') {
         const unit = behavior.axis === 'heading' ? 'deg' : 'mm';
         if (b.rule === 'value' && node.unit !== unit)
@@ -374,10 +322,165 @@ function covers(intervals, min, max) {
     }
     return false;
 }
+/** A legend role a consumer chooses a legend by: lower case letters, digits and `-`. */
+const LEGEND_ROLE = /^[a-z0-9][a-z0-9-]*$/;
+/**
+ * A table binding (ADR-0166 3, 6): its targets are the figure's, its lookup fits the field, every look is one its
+ * targets take and has no column for another, a closed field's every value has a look or there is a default, and a range
+ * table's intervals do not overlap.
+ */
+function checkTable(b, node, targets, path) {
+    const domain = domainOf(b.id, path);
+    const t = b.targets;
+    if (!t || typeof t !== 'object' || Array.isArray(t))
+        fail('ASSET_SCHEMA', `${path}.targets`, 'object required');
+    fields(t, [], ['parts', 'inputs', 'group'], `${path}.targets`);
+    for (const k of ['parts', 'inputs'])
+        if (t[k] !== undefined && (!Array.isArray(t[k]) || t[k].some((x) => typeof x !== 'string' || !x)))
+            fail('ASSET_SCHEMA', `${path}.targets.${k}`, 'a list of ids');
+    if (t.group !== undefined && (typeof t.group !== 'string' || !t.group))
+        fail('ASSET_SCHEMA', `${path}.targets.group`, 'a nonempty string');
+    const target = (what, message, id) => refuse(`${path}.targets`, message, { reason: 'data-table-target', binding: b.id, what, ...(id !== undefined ? { id } : {}) });
+    const parts = t.parts ?? [];
+    const inputs = t.inputs ?? [];
+    if (!parts.length && !inputs.length && t.group === undefined)
+        target('none', 'a table shows on a part, a state input, a motion group, or more');
+    parts.forEach((p, i) => {
+        if (!targets.parts.has(p))
+            target('part', `${p} is not a part of this figure`, p);
+        if (parts.indexOf(p) !== i)
+            target('part', `${p} is named twice`, p);
+    });
+    inputs.forEach((s, i) => {
+        if (!targets.states.has(s))
+            target('input', `${s} is not a state input of this figure`, s);
+        if (inputs.indexOf(s) !== i)
+            target('input', `${s} is named twice`, s);
+    });
+    if (t.group !== undefined && !targets.groups.has(t.group))
+        target('group', `${t.group} is not a motion group of this figure`, t.group);
+    if (b.lookup !== 'code' && b.lookup !== 'ranges')
+        fail('ASSET_SCHEMA', `${path}.lookup`, 'code or ranges');
+    if (!isValue(node))
+        return domain('kind', `${b.accessor} is ${node.kind === 'list' ? 'a list' : 'an object'}; a table reads one value`);
+    if (b.lookup === 'code' && node.kind === 'number')
+        return domain('kind', `${b.accessor} is a number; a table reads it by ranges`);
+    if (b.lookup === 'ranges' && node.kind !== 'number')
+        return domain('kind', `a range table reads a number; ${b.accessor} is ${node.kind === 'text' ? 'a text' : 'true or false'}`);
+    const table = b.table;
+    if (!table || typeof table !== 'object' || Array.isArray(table))
+        fail('ASSET_SCHEMA', `${path}.table`, 'an object of looks');
+    const keys = Object.keys(table).filter(k => k !== 'default');
+    if (b.lookup === 'code') {
+        const closed = closedDomain(node);
+        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 });
+            if (!closed.every(v => Object.hasOwn(table, String(v))) && !Object.hasOwn(table, 'default'))
+                domain('default', `not every value of ${b.accessor} has a look; give a default`);
+        }
+    }
+    else {
+        const intervals = [];
+        for (const k of keys) {
+            const iv = figureIntervalOf(k);
+            if (!iv)
+                return domain('cases', `${k} is not an interval: from~to, either end may be left out`, { value: k });
+            const other = intervals.find(([from, to]) => iv[0] < to && from < iv[1]);
+            if (other)
+                domain('overlap', `${other[2]} and ${k} overlap; a value has one look`, { value: k });
+            intervals.push([iv[0], iv[1], k]);
+        }
+        const n = node;
+        if (!Object.hasOwn(table, 'default') && !covers(intervals.map(([from, to]) => [from, to]), n.min ?? -Infinity, n.max ?? Infinity))
+            domain('default', `the intervals leave values of ${b.accessor} without a look; give a default`);
+    }
+    for (const [key, look] of Object.entries(table)) {
+        const at = `${path}.table.${key}`;
+        if (!look || typeof look !== 'object' || Array.isArray(look))
+            fail('ASSET_SCHEMA', at, 'object required');
+        fields(look, [], ['color', 'effect', 'values', 'clip', 'speed', 'paused'], at);
+        const bad = (what, message, extra = {}) => refuse(`${at}.${what === 'column' ? extra.id : what}`, message, { reason: 'data-table-entry', binding: b.id, key, what, ...extra });
+        const column = (name, has) => {
+            if (look[name] !== undefined && !has)
+                bad('column', `${name} goes to no target of ${b.id}`, { id: name });
+        };
+        column('color', parts.length > 0);
+        column('effect', parts.length > 0);
+        column('values', inputs.length > 0);
+        for (const [name] of GROUP_COLUMNS)
+            column(name, t.group !== undefined);
+        if (look.color !== undefined && !isFigureColour(look.color))
+            bad('color', 'a colour is #RRGGBB', { value: look.color });
+        if (look.effect !== undefined) {
+            const e = look.effect;
+            if (!e || typeof e !== 'object' || Array.isArray(e))
+                fail('ASSET_SCHEMA', `${at}.effect`, 'object required');
+            fields(e, ['kind'], ['hz'], `${at}.effect`);
+            if (e.kind !== 'blink' && e.kind !== 'glow')
+                bad('effect', 'an effect is blink or glow', { value: e.kind });
+            if (e.hz !== undefined && !(finite(e.hz) && e.hz > 0))
+                bad('effect', 'hz is a positive number', { value: e.hz });
+        }
+        if (look.values !== undefined) {
+            if (!look.values || typeof look.values !== 'object' || Array.isArray(look.values))
+                fail('ASSET_SCHEMA', `${at}.values`, 'an object of values');
+            for (const [id, v] of Object.entries(look.values)) {
+                if (!inputs.includes(id))
+                    bad('values', `${id} is not a target of ${b.id}`, { id });
+                const input = targets.states.get(id);
+                if (!finite(v) || v < input.min || v > input.max)
+                    bad('values', `${String(v)} is outside ${id}, ${input.min} to ${input.max}`, { id, value: v });
+            }
+        }
+        if (look.clip !== undefined && (typeof look.clip !== 'string' || !targets.groups.get(t.group).includes(look.clip)))
+            bad('clip', `${String(look.clip)} is not a clip of ${t.group}`, { value: look.clip });
+        if (look.speed !== undefined && !(finite(look.speed) && look.speed >= 0 && look.speed <= FIGURE_MOTION_SPEED_MAX))
+            bad('speed', `a motion speed is 0 to ${FIGURE_MOTION_SPEED_MAX}`, { value: look.speed });
+        if (look.paused !== undefined && typeof look.paused !== 'boolean')
+            bad('paused', 'a pause is true or false', { value: look.paused });
+    }
+    if (b.legend !== undefined) {
+        if (!b.legend || typeof b.legend !== 'object' || Array.isArray(b.legend))
+            fail('ASSET_SCHEMA', `${path}.legend`, 'object required');
+        fields(b.legend, ['role'], [], `${path}.legend`);
+        if (typeof b.legend.role !== 'string' || !LEGEND_ROLE.test(b.legend.role))
+            refuse(`${path}.legend.role`, `${String(b.legend.role)} is not a role: lower case letters, digits and -`, { reason: 'data-legend-invalid', binding: b.id, role: String(b.legend.role) });
+    }
+}
 function checkBinding(b, schema, targets, path) {
-    fields(b, ['id', 'accessor', 'behavior', 'rule'], ['param'], path);
+    if (!b || typeof b !== 'object' || Array.isArray(b))
+        fail('ASSET_SCHEMA', path, 'object required');
+    const table = b.rule === 'table';
+    if (table)
+        fields(b, ['id', 'accessor', 'rule', 'lookup', 'targets', 'table'], ['label', 'legend'], path);
+    else
+        fields(b, ['id', 'accessor', 'behavior', 'rule'], ['label', '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) });
+    if (b.label !== undefined && (typeof b.label !== 'string' || !b.label.trim()))
+        fail('ASSET_SCHEMA', `${path}.label`, 'a name shown to a person, or none');
+    /* The accessor goes down the schema to what the binding reads. */
+    const accessorRefused = (accessor, why) => refuse(`${path}.accessor`, `${accessor}: ${why}`, { reason: 'data-accessor-invalid', binding: b.id, accessor, why });
+    const found = () => {
+        const steps = parseFigureAccessor(b.accessor);
+        if (!steps)
+            accessorRefused(String(b.accessor), 'syntax');
+        const at = nodeAt(schema, steps);
+        if ('why' in at)
+            return accessorRefused(b.accessor, at.why);
+        return at;
+    };
+    if (table) {
+        const { node } = found();
+        if (node.kind === 'list')
+            accessorRefused(b.accessor, 'list-needs-index');
+        else if (!isValue(node))
+            accessorRefused(b.accessor, 'not-a-value');
+        checkTable(b, node, targets, path);
+        return b;
+    }
     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');
@@ -389,19 +492,10 @@ function checkBinding(b, schema, targets, path) {
         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);
+    const { node } = found();
     if (behavior.kind === 'items') {
-        if (found.node.kind === 'list') {
-            const item = found.node.item;
+        if (node.kind === 'list') {
+            const item = 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']) {
@@ -418,58 +512,20 @@ function checkBinding(b, schema, targets, path) {
                     accessorRefused(`${b.accessor}[].${rel}`, 'not-a-value');
             }
         }
-        else if (isValue(found.node)) {
+        else if (isValue(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')
+    else if (node.kind === 'list')
         accessorRefused(b.accessor, 'list-needs-index');
-    else if (!isValue(found.node))
+    else if (!isValue(node))
         accessorRefused(b.accessor, 'not-a-value');
-    checkRule(b, found.node, targets, path);
+    checkRule(b, node, targets, path);
     return b;
 }
-function checkPort(p, targets, path) {
-    fields(p, ['id', 'label', 'tokens', 'parts'], ['group', 'states'], 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.states !== undefined && !Array.isArray(p.states))
-        fail('ASSET_SCHEMA', `${path}.states`, 'a list of state inputs');
-    const states = p.states ?? [];
-    if (!p.tokens.length && !p.parts.length && !states.length)
-        invalid('token', 'a status port shows on a colour token, a part, a state input, or more');
-    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));
-    const offered = new Set();
-    states.forEach((s, i) => {
-        const at = `${path}.states[${i}]`;
-        if (!s || typeof s !== 'object' || Array.isArray(s))
-            fail('ASSET_SCHEMA', at, 'object required');
-        fields(s, ['input', 'sourceMode'], [], at);
-        if (s.sourceMode !== 'observed' && s.sourceMode !== 'commanded')
-            fail('ASSET_SCHEMA', `${at}.sourceMode`, 'observed or commanded');
-        if (typeof s.input !== 'string' || !targets.states.has(s.input))
-            invalid('state', `${String(s.input)} is not a state input of this figure`, String(s.input));
-        if (offered.has(s.input))
-            invalid('state', `${s.input} is offered twice`, s.input);
-        offered.add(s.input);
-    });
-    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.
@@ -478,65 +534,38 @@ export function validateFigureDataInterface(asset) {
     const di = asset.dataInterface;
     if (di === undefined)
         return;
-    fields(di, ['version', 'schema', 'bindings'], ['ports'], 'dataInterface');
+    fields(di, ['version', 'schema', 'bindings'], [], '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();
-    /* The state inputs ports offer and the motion groups they select clips in: no other port and no binding writes them (ADR-0051 2.3). */
-    const portWrites = new Map();
-    const writeOnce = (target, id, writer, path) => {
-        const other = portWrites.get(`${target} ${id}`);
-        if (other)
-            refuse(path, `${other.kind} ${other.id} and ${writer.kind} ${writer.id} both write ${target} ${id}; one data writer each`, {
-                reason: 'data-writer-duplicate',
-                target,
-                id,
-                writers: [other, writer]
-            });
-        portWrites.set(`${target} ${id}`, writer);
-    };
-    (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);
-        (port.states ?? []).forEach((s, j) => writeOnce('state', s.input, { kind: 'port', id: port.id }, `dataInterface.ports[${i}].states[${j}]`));
-        if (port.group !== undefined)
-            writeOnce('motion-clip', port.group, { kind: 'port', id: port.id }, `dataInterface.ports[${i}].group`);
-    });
     const ids = new Set();
+    /* One writer each (ADR-0166 6): a state input, a motion group's clip, speed or pause -- by a value binding or a table. */
     const writers = new Map();
+    const write = (key, behavior, id, binding, path) => {
+        const other = writers.get(key);
+        if (other !== undefined)
+            refuse(path, `${other} and ${binding} both write ${key}; one writer each`, { reason: 'data-behavior-duplicate', bindings: [other, binding], behavior, id });
+        writers.set(key, binding);
+    };
     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);
-        /* A binding against a port that offers its input or selects its group's clip; two bindings on one are refused below, as before. */
-        const writes = binding.behavior;
-        const target = writes.kind === 'state' ? ['state', writes.input] : writes.kind === 'motion-clip' ? ['motion-clip', writes.group] : null;
-        if (target && portWrites.has(`${target[0]} ${target[1]}`))
-            writeOnce(target[0], target[1], { kind: 'binding', id: binding.id }, `${path}.behavior`);
-        const key = writeKey(binding.behavior);
-        if (key === null)
+        if (binding.rule === 'table') {
+            for (const w of tableWrites(binding))
+                write(w.key, w.behavior, w.id, binding.id, `${path}.targets`);
             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);
+        }
+        const key = writeKey(binding.behavior);
+        if (key !== null)
+            write(key, binding.behavior.kind, behaviorId(binding.behavior), binding.id, `${path}.behavior`);
     });
 }
 /** The data interface of an asset, checked, with what the schema has at each binding; null when the figure declares none. */
@@ -548,7 +577,7 @@ export function compileFigureDataInterface(asset) {
     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') {
+        if (binding.rule !== 'table' && binding.behavior.kind === 'items' && node.kind === 'list') {
             const item = node.item;
             itemNodes = {};
             for (const role of ['id', 'type', 'place', 'stack', 'status']) {
@@ -576,7 +605,7 @@ export function compileFigureDataInterface(asset) {
         }
     };
     walk(di.schema, '');
-    return Object.freeze({ schema: Object.freeze(di.schema), ports: Object.freeze(di.ports ?? []), bindings: Object.freeze(bindings), jsonFields: Object.freeze(jsonFields) });
+    return Object.freeze({ schema: Object.freeze(di.schema), 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) {
@@ -587,7 +616,7 @@ export function figureDataRows(di) {
     const asRow = (accessor) => accessor.replace(/\[\d+\]/g, '[]');
     for (const b of di.bindings) {
         note(asRow(b.accessor), b.id);
-        if (b.behavior.kind === 'items')
+        if (b.rule !== 'table' && 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);
@@ -679,25 +708,36 @@ export function inferFigureDataSchema(sample) {
     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. */
+/**
+ * The interface after a part was renamed: a state input the part owned (`<part>.…`) and a table's part follow it -- in
+ * a table, its targets and the values of its looks.
+ */
 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))
+        bindings: asset.dataInterface.bindings.map(b => {
+            if (b.rule !== 'table')
+                return b.behavior.kind === 'state' ? { ...b, behavior: { ...b.behavior, input: moved(b.behavior.input) } } : b;
+            const { parts, inputs, group } = b.targets;
+            return {
+                ...b,
+                targets: { ...(parts ? { parts: parts.map(moved) } : {}), ...(inputs ? { inputs: inputs.map(moved) } : {}), ...(group !== undefined ? { group } : {}) },
+                table: Object.fromEntries(Object.entries(b.table).map(([key, look]) => [key, look.values ? { ...look, values: Object.fromEntries(Object.entries(look.values).map(([id, v]) => [moved(id), v])) } : look]))
+            };
+        })
     };
 }
-/** The interface after a clip was renamed: every map that selects it in a motion group selects it by its new name. */
+/** The interface after a clip was renamed: every table 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])) }
+        bindings: asset.dataInterface.bindings.map(b => b.rule === 'table' && b.targets.group === group
+            ? { ...b, table: Object.fromEntries(Object.entries(b.table).map(([key, look]) => [key, look.clip === from ? { ...look, clip: to } : look])) }
             : b)
     };
 }
@@ -749,7 +789,9 @@ export function renameDataField(di, accessor, to) {
             return at === names.length - 1 && names.every((name, i) => prefix[i] === name) ? { field: to } : step;
         }));
     };
-    out.bindings = out.bindings.map(b => {
+    out.bindings = out.bindings.map((b) => {
+        if (b.rule === 'table')
+            return { ...b, accessor: through(b.accessor) };
         const next = { ...b, accessor: through(b.accessor) };
         if (b.behavior.kind !== 'items')
             return next;