animl-cli 0.0.0-stage → 0.1.0

package/modules/derive/SPEC.md

@@ -0,0 +1,66 @@
+# derive
+
+Optional `derive` (with `data` and `bind`) adds read-only computed scalar model properties.
+A number, string, bool, color or enum property may declare `value` as a bind expression and
+optionally `convert` naming a converter/group (requires `convert`). JSON and AniML use the
+same names: `<string name="label" value="$score" convert="points"/>`.
+
+Inside that expression `$name` resolves against the containing instance, including each list
+item. `$main:path` remains absolute. Computed properties can depend on other computed properties;
+cycles fail with `derive-cycle`. Values initialize per player and recompute once per step after
+queued writes and before clocks and machine guards. A single write to a source property on a
+settled player therefore updates derived guards and the selected state in the same step, including
+`step(0)`. Stateful converters receive the step's `dt` exactly once. Transition/entry actions that
+change sources after this snapshot affect computed values on the following step; there is no
+feedback iteration. Bindings and events/subscriptions observe the computed snapshot from this step. Read paths work in conditions, bindings, events, CLI samples and host handles.
+
+`set`, `copy`, `toggle`, input `write`, reverse binding modes and instance initializers reject
+computed destinations with `read-only-path`, an authored JSON pointer, message and hint. Host
+handle `.set()` throws `DataError` with the same code. Write the source properties instead.
+`derive-type` rejects non-scalar or incompatible declarations; `derive-converter` identifies
+missing converters. Expression errors retain bind codes. Computed values use the declared scalar
+normalization and numeric bounds. Computed numbers evaluate the expression before initial
+bounds are applied; the stored-property fallback zero is not an initial computed value. Bool
+results become 0/1 for number properties before clamping. State and converter caches belong to each player/instance.
+
+The scope-and-binding approach follows the metadata separation in
+[graph research](../../docs/research/rive-format-and-graph.md) §6 and avoids feedback iteration
+as discussed in [state research](../../docs/research/rive-animation-and-state.md) §C.
+No implementation or text is copied from Rive. Documents without computed declarations receive
+no derived scope, resolver, scheduler or per-step work.
+
+This completes instance-relative computed evaluation, not upward component lookup; the broader
+`data.binding-relative` parity row remains pending. See oracle/README.md for the native evidence
+boundary. Examples under examples/ compile through the ordinary CLI.
+
+
+## Native evidence (2026-11-06)
+
+Fresh CLI 1.9.1 headless data dumps verify formatted score labels, bounded formula
+values and relative evaluation in three list instances, including source updates.
+Seven paired probes verify `<`, `<=`, `==`, `!=`, `and`, `or`, `not` settled results
+for number and bool targets through native transition comparators. All nine cases
+use exact comparisons. See [the evidence report](oracle/README.md) for raw dumps,
+commands, mappings and scheduling/precision limits.
+
+The read-only contract above remains Anima's contract: the tested native
+converter-to-model composition permits destination writes, including retaining a
+manual label after an advance. Its read-only parity comparison is an evidenced
+skip, not verified parity or a decided intentional difference. No normative
+behavior changes in this evidence follow-up.
+
+**Intentional difference from Rive:** a computed property is read-only. Rive's closest counterpart
+accepts a write to the derived destination and keeps it (1 accepted write) until the next source
+change; Anima rejects it with `read-only-path` (0). The captured evidence is the read-only skip in
+`tests/oracle/`; it is recorded, never counted as a passing comparison.
+
+
+## String length paths
+
+With `derive`, every readable string data path also exposes a numeric, read-only `.length`:
+`$title.length`, `$other:title.length`, `$child.title.length`, `$items.0.title.length` and relative
+component paths. The length is JavaScript UTF-16 code units (empty string 0; `A😀` 3), not grapheme
+clusters. It updates from the current string, including computed strings, at the ordinary binding
+position and works in bindings, computed properties, repeat counts, samples and data reads.
+Computed dependencies through `.length` participate in cycle detection; writes report `read-only-path`.
+No new bind grammar or per-character converter is added.

package/modules/derive/examples/scoreboard.ani

@@ -0,0 +1,121 @@
+{
+  "anima": "0.1",
+  "name": "derived-scoreboard",
+  "grid": 20,
+  "requires": ["data", "bind", "derive", "convert"],
+  "nodes": [
+    {
+      "id": "a",
+      "type": "circle",
+      "center": [4, 10],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      },
+      "properties": {
+        "label": ""
+      }
+    },
+    {
+      "id": "b",
+      "type": "circle",
+      "center": [10, 10],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      },
+      "properties": {
+        "label": ""
+      }
+    },
+    {
+      "id": "c",
+      "type": "circle",
+      "center": [16, 10],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      },
+      "properties": {
+        "label": ""
+      }
+    }
+  ],
+  "bind": {
+    "a.properties.label": "$players.0.label",
+    "b.properties.label": "$players.1.label",
+    "c.properties.label": "$players.2.label",
+    "a.x": "$players.0.score >= $players.1.score and $players.0.score >= $players.2.score",
+    "b.x": "$players.1.score > $players.0.score and $players.1.score >= $players.2.score",
+    "c.x": "$players.2.score > $players.0.score and $players.2.score > $players.1.score"
+  },
+  "data": {
+    "models": {
+      "Player": {
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "score": {
+            "type": "number",
+            "min": 0,
+            "max": 2000
+          },
+          "label": {
+            "type": "string",
+            "value": "$score",
+            "convert": "points"
+          },
+          "milestone": {
+            "type": "bool",
+            "value": "$score >= 1500"
+          }
+        }
+      },
+      "Board": {
+        "properties": {
+          "players": {
+            "type": "list",
+            "of": "Player"
+          }
+        }
+      }
+    },
+    "instances": {
+      "main": {
+        "model": "Board",
+        "default": true,
+        "values": {
+          "players": [
+            {
+              "name": "Ada",
+              "score": 1250
+            },
+            {
+              "name": "Lin",
+              "score": 980
+            },
+            {
+              "name": "Sam",
+              "score": 40
+            }
+          ]
+        }
+      }
+    }
+  },
+  "converters": {
+    "grouped": {
+      "type": "number-format",
+      "decimals": 0,
+      "grouping": true
+    },
+    "suffix": {
+      "type": "template",
+      "text": "{0} pts"
+    },
+    "points": {
+      "chain": ["grouped", "suffix"]
+    }
+  }
+}

package/modules/derive/examples/scoreboard.animl

@@ -0,0 +1,27 @@
+<anima version="0.1" name="derived-scoreboard" grid="20" requires="data bind derive convert">
+  <model name="Player">
+    <string name="name"/>
+    <number name="score" min="0" max="2000"/>
+    <string name="label" value="$score" convert="points"/>
+    <bool name="milestone" value="$score >= 1500"/>
+  </model>
+  <model name="Board">
+    <list name="players" of="Player"/>
+  </model>
+  <instance name="main" model="Board" default="true">
+    <set path="players"
+        value="[{&quot;name&quot;:&quot;Ada&quot;,&quot;score&quot;:1250},{&quot;name&quot;:&quot;Lin&quot;,&quot;score&quot;:980},{&quot;name&quot;:&quot;Sam&quot;,&quot;score&quot;:40}]"/>
+  </instance>
+  <converter name="grouped" type="number-format" decimals="0" grouping="true"/>
+  <converter name="suffix" type="template" text="{0} pts"/>
+  <converter-group name="points" chain="grouped suffix"/>
+  <circle id="a" cx="4" cy="10" r="1" fill="#000" data-label=""/>
+  <circle id="b" cx="10" cy="10" r="1" fill="#000" data-label=""/>
+  <circle id="c" cx="16" cy="10" r="1" fill="#000" data-label=""/>
+  <bind target="a.properties.label" value="$players.0.label"/>
+  <bind target="b.properties.label" value="$players.1.label"/>
+  <bind target="c.properties.label" value="$players.2.label"/>
+  <bind target="a.x" value="$players.0.score >= $players.1.score and $players.0.score >= $players.2.score"/>
+  <bind target="b.x" value="$players.1.score > $players.0.score and $players.1.score >= $players.2.score"/>
+  <bind target="c.x" value="$players.2.score > $players.0.score and $players.2.score > $players.1.score"/>
+</anima>

package/modules/derive/manifest.source

@@ -0,0 +1,24 @@
+export const after = ['data', 'bind', 'convert'];
+export default {
+  name: 'derive',
+  summary: 'Derived data: computed, read-only model properties from expressions.',
+  after,
+  core: { entry: 'core/index.ts', export: 'derive' },
+  web: [{ name: 'derive', budget: 2624 }],
+  adapters: {
+    'packages/core/src/modules/derive/index.ts': 'core/index.ts',
+    'packages/web/src/derive.ts': 'web/index.ts',
+  },
+  exports: {
+    'core:./derive': 'packages/core/src/modules/derive/index.ts',
+    'web:./derive': 'packages/web/src/derive.ts',
+  },
+  tests: [
+    'modules/derive/test/**/*.test.ts',
+    'packages/markup/test/corpus.test.ts',
+    'packages/markup/test/names.test.ts',
+    'packages/markup/test/decompile.test.ts',
+  ],
+  conformance: ['derive-', 'bind-comparisons'],
+  docs: ['modules/derive/SPEC.md'],
+};

package/modules/devtools/SPEC.md

@@ -0,0 +1,25 @@
+# Optional browser diagnostics
+
+Import `@anima-format/web/devtools` to install these host-only APIs. No document keys,
+registry spellings, validation diagnostics, CLI switches or Player.step changes are introduced.
+
+- `icon.stats` is a detached `{fps, frameMs, frames}` snapshot. `frames` and `fps` count
+  scheduler frame calls in the trailing 1000 ms; `frameMs` is their mean measured execution
+  time (step and draw), or zero with no samples. Paused/settled idle time contributes no frames.
+- `icon.perfMarks = true` or the host `perf` attribute records `anima:frame:start` and
+  `anima:frame` measures around frame execution. The temporary mark is cleared after measuring.
+- Initialization timing (same opt-in): at an icon's first marked frame, a mark `anima:load` at the
+  time the element connected (or when devtools registered, for icons connected before it) and a
+  measure `anima:first-frame` from that mark to the end of the frame; recorded once per icon.
+  Measures remain available to PerformanceObserver/the performance timeline for the host to clear.
+- `AnimaIcon.warnings = 'once' | 'always' | 'off' | { off: readonly string[] }`, default `once`, controls the
+  `AnimaIcon.warn(code, message)` policy hook. Once means one warning per code per page. An object suppresses only its listed stable IDs;
+  other IDs are emitted on every call. Suppressed calls do not consume the once history.
+  Changing policy preserves that history.
+  There are currently no shipped runtime deprecation/console warnings to redirect; loader
+  diagnostics and errors are unchanged. Future deprecations must use this hook.
+
+Without this import the base runtime has identical behaviour and no diagnostics instrumentation.
+The optional hook/wrapper follows the opt-in marks recommendation in
+[web runtime research](../../docs/research/rive-web-runtime.md), points 12–13.
+Oracle skipped: browser scheduling and Performance APIs have no faithful native local CLI counterpart.

package/modules/devtools/capabilities/host-api-deprecation-policy/example.ani

@@ -0,0 +1,16 @@
+{
+  "anima": "0.1",
+  "name": "host-api-deprecation-policy",
+  "grid": 20,
+  "nodes": [
+    {
+      "id": "probe",
+      "type": "circle",
+      "center": [10, 10],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      }
+    }
+  ]
+}

package/modules/devtools/capabilities/host-api-deprecation-policy/example.animl

@@ -0,0 +1,3 @@
+<anima version="0.1" name="host-api-deprecation-policy" grid="20">
+  <circle id="probe" cx="10" cy="10" r="1" fill="#000"/>
+</anima>

package/modules/devtools/capabilities/host-api-fps-counter/example.ani

@@ -0,0 +1,16 @@
+{
+  "anima": "0.1",
+  "name": "host-api-fps-counter",
+  "grid": 20,
+  "nodes": [
+    {
+      "id": "probe",
+      "type": "circle",
+      "center": [10, 10],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      }
+    }
+  ]
+}

package/modules/devtools/capabilities/host-api-fps-counter/example.animl

@@ -0,0 +1,9 @@
+<anima version="0.1" name="host-api-fps-counter" grid="20">
+  <circle id="probe" cx="10" cy="10" r="1" fill="#000"/>
+  <timeline name="pulse" duration="1" loop="loop">
+    <track target="probe.x">0 0; 0.5 4; 1 0</track>
+  </timeline>
+  <layer name="pulse" initial="run">
+    <state name="run" play="pulse"/>
+  </layer>
+</anima>

package/modules/devtools/capabilities/host-api-performance-marks/example.ani

@@ -0,0 +1,16 @@
+{
+  "anima": "0.1",
+  "name": "host-api-performance-marks",
+  "grid": 20,
+  "nodes": [
+    {
+      "id": "probe",
+      "type": "circle",
+      "center": [10, 10],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      }
+    }
+  ]
+}

package/modules/devtools/capabilities/host-api-performance-marks/example.animl

@@ -0,0 +1,3 @@
+<anima version="0.1" name="host-api-performance-marks" grid="20">
+  <circle id="probe" cx="10" cy="10" r="1" fill="#000"/>
+</anima>

package/modules/devtools/capabilities/host-api-stop/example.ani

@@ -0,0 +1,16 @@
+{
+  "anima": "0.1",
+  "name": "host-api-stop",
+  "grid": 20,
+  "nodes": [
+    {
+      "id": "probe",
+      "type": "circle",
+      "center": [10, 10],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      }
+    }
+  ]
+}

package/modules/devtools/capabilities/host-api-stop/example.animl

@@ -0,0 +1,3 @@
+<anima version="0.1" name="host-api-stop" grid="20">
+  <circle id="probe" cx="10" cy="10" r="1" fill="#000"/>
+</anima>

package/modules/devtools/manifest.source

@@ -0,0 +1,13 @@
+export const after = [];
+export default {
+  name: 'devtools',
+  summary: 'Authoring tool: host-only inspection APIs for debugging scenes in the browser.',
+  after,
+  core: null,
+  web: [{ name: 'devtools', budget: 448, authoring: true }],
+  adapters: { 'packages/web/src/devtools.ts': 'web/index.ts' },
+  exports: { 'web:./devtools': 'packages/web/src/devtools.ts' },
+  tests: ['modules/devtools/test/**/*.test.ts', 'packages/web/test/browser.test.ts'],
+  conformance: [],
+  docs: ['modules/devtools/SPEC.md'],
+};

package/modules/events/examples/events.ani

@@ -0,0 +1,75 @@
+{
+  "anima": "0.1",
+  "name": "events",
+  "grid": 20,
+  "requires": ["events"],
+  "inputs": {
+    "count": {
+      "type": "number"
+    },
+    "flag": {
+      "type": "bool"
+    }
+  },
+  "nodes": [
+    {
+      "id": "a",
+      "type": "circle",
+      "center": [10, 10],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      }
+    }
+  ],
+  "timelines": {
+    "t": {
+      "duration": 1,
+      "tracks": {
+        "a.x": [
+          [0, 0],
+          [1, 10]
+        ]
+      },
+      "events": [
+        [0, "ping"],
+        [0.5, "ping"],
+        [1, "ping"]
+      ]
+    }
+  },
+  "machine": {
+    "layers": {
+      "main": {
+        "initial": "s",
+        "states": {
+          "s": {
+            "play": "t"
+          }
+        }
+      }
+    }
+  },
+  "eventDefs": {
+    "ping": {
+      "payload": {
+        "count": {
+          "type": "number",
+          "input": "count"
+        },
+        "flag": {
+          "type": "bool",
+          "input": "flag"
+        },
+        "label": {
+          "type": "string",
+          "value": "hello"
+        },
+        "x": {
+          "type": "number",
+          "address": "a.x"
+        }
+      }
+    }
+  }
+}

package/modules/events/examples/events.animl

@@ -0,0 +1,23 @@
+<anima version="0.1" name="events" grid="20" requires="events">
+  <number name="count"/>
+  <bool name="flag"/>
+
+  <circle id="a" cx="10" cy="10" r="1" fill="#000"/>
+
+  <timeline name="t" duration="1">
+    <track target="a.x">
+      0  0
+      1  10
+    </track>
+    <event at="0" name="ping"/>
+    <event at="0.5" name="ping"/>
+    <event at="1" name="ping"/>
+  </timeline>
+
+  <event-def name="ping"
+      payload="{&quot;count&quot;:{&quot;type&quot;:&quot;number&quot;,&quot;input&quot;:&quot;count&quot;},&quot;flag&quot;:{&quot;type&quot;:&quot;bool&quot;,&quot;input&quot;:&quot;flag&quot;},&quot;label&quot;:{&quot;type&quot;:&quot;string&quot;,&quot;value&quot;:&quot;hello&quot;},&quot;x&quot;:{&quot;type&quot;:&quot;number&quot;,&quot;address&quot;:&quot;a.x&quot;}}"/>
+
+  <layer name="main" initial="s">
+    <state name="s" play="t"/>
+  </layer>
+</anima>

package/modules/events/examples/share-evidence/README.md

@@ -0,0 +1,48 @@
+# P4d-3 share acceptance evidence
+
+The source is `../share.animl` (40 lines, 1,960 characters), compiled to `../share.ani`.
+The counter is one expression write; three states distinguish rest, pulse and milestone pulse.
+No host code increments the input. The own 80 ms mono 16-bit 16 kHz WAV is a decaying 660 Hz sine:
+`round(8000*sin(2*pi*660*i/16000)*(1-i/1280))`, for samples 0 through 1279.
+
+From the repository root:
+
+```sh
+node packages/cli/src/main.ts validate modules/events/examples/share.animl
+node tools/build-animl.ts --check
+node packages/cli/src/main.ts sample modules/events/examples/share.animl --script modules/events/examples/share-evidence/clicks.script
+node packages/cli/src/main.ts sample modules/events/examples/share.animl --script modules/events/examples/share-evidence/pulse.script
+node packages/cli/src/main.ts sample modules/events/examples/share.animl --script modules/events/examples/share-evidence/interrupt.script
+python3 modules/events/examples/share-evidence/verify.py
+npm run test:scope -- bind events core markup conformance components
+node packages/cli/src/main.ts render modules/events/examples/share.animl --compare docs/benchmarks/runs/2026-11-09-p4d/animl/expected-rest.svg -o /tmp/p4d-share-rest.png
+```
+
+The three `.jsonl` files retain raw public CLI snapshots; the independent Python verifier checks:
+
+1. Count 0 at rest, then 1–25. Pulse curves sampled every 0.05 seconds match each 0.3-second
+   triangle, peaking at 1.3 at 0.15/0.20/0.25 seconds with pivots at the circles' centres.
+2. All 25 pulse entries emit `shared` at local time 0 with `{count:n,channel:"button"}`.
+   At click 15, global time 5.6 s, payload count is 15; click 25 is global time 9.6 s, count 25.
+3. All 25 completions emit `pulse-done` at local time 0.4 (global 0.4 through 10 s).
+   The interruption script restarts at 0.1 s and reports only the final completion at global 0.5 s.
+4. Milestones occur only at counts 5/10/15/20/25 (global 1.6/3.6/5.6/7.6/9.6 s), each carrying
+   `https://example.org/thanks`, `_blank`. The browser asserts no navigation without permission.
+5. Every shared event requests `tone`. The events browser test loads this exact document and WAV
+   bytes, drives fifteen clicks through the public frame API, verifies payloads and milestones,
+   and checks one cached decode and fifteen source-start requests through the real events audio
+   path using a mocked AudioContext. This is request-path verification, allowed by the brief;
+   it does not claim audible playback. Existing events audio tests retain activation, volume,
+   failure, resolver and lifetime checks. Both Chromium and Firefox pass.
+6. The rest document contains only the specified two strokes and three ink circles. CLI pixel
+   comparison with the benchmark's unchanged independent rest reference: **0 differing pixels,
+   max channel difference 0, tolerance 0**. No benchmark-run file was modified.
+
+The CLI test also compares `.ani` and `.animl` outputs byte-for-byte with `clicks.jsonl`.
+`anima schema listener`, `state`, `transition`, and `--json-schema` expose the added forms.
+Seven hand-derived conformance cases cover increment past ten, clamp, same-snapshot writes,
+machine action order, modulo, typed payload expressions, and next-step machine-action listeners.
+
+Independent comparative oracle capture is explicitly pending, not passing, in the scaffolder's
+`tests/oracle/data-bind-listener-actions/todo.json`. The parity row remains planned. No Rive
+source, docs text or binary was used. See `modules/events/P4D-3-RESULTS.md` for costs and checks.