animl-cli 0.0.0-stage → 0.1.1

package/modules/motion/examples/sync.ani

@@ -0,0 +1,272 @@
+{
+  "anima": "0.1",
+  "name": "sync",
+  "title": "Sync",
+  "grid": 20,
+  "requires": ["motion", "bind"],
+  "colors": {
+    "ink": "#141413",
+    "accent": "#d97757"
+  },
+  "a11y": {
+    "role": "button",
+    "label": "Sync",
+    "activate": "syncing",
+    "pressed": "syncing"
+  },
+  "inputs": {
+    "syncing": {
+      "type": "bool"
+    },
+    "hover": {
+      "type": "bool"
+    },
+    "phase": {
+      "type": "number",
+      "default": 0,
+      "min": 0,
+      "max": 1
+    }
+  },
+  "hit": {
+    "rect": [0, 0, 20, 20]
+  },
+  "nodes": [
+    {
+      "id": "peek",
+      "type": "group",
+      "pivot": [10, 10],
+      "children": [
+        {
+          "id": "arrows",
+          "type": "group",
+          "pivot": [10, 10],
+          "children": [
+            {
+              "id": "top",
+              "type": "arc",
+              "center": [10, 10],
+              "r": 6,
+              "from": -165,
+              "to": -15,
+              "stroke": {
+                "color": "ink",
+                "width": 1.5,
+                "cap": "round"
+              }
+            },
+            {
+              "id": "top-tip",
+              "type": "path",
+              "d": "M14.064 7.447L15.796 8.447L16.796 6.715",
+              "stroke": {
+                "color": "ink",
+                "width": 1.5,
+                "cap": "round",
+                "join": "round"
+              }
+            },
+            {
+              "id": "bottom",
+              "type": "arc",
+              "center": [10, 10],
+              "r": 6,
+              "from": 15,
+              "to": 165,
+              "stroke": {
+                "color": "ink",
+                "width": 1.5,
+                "cap": "round"
+              }
+            },
+            {
+              "id": "bottom-tip",
+              "type": "path",
+              "d": "M5.936 12.553L4.204 11.553L3.204 13.285",
+              "stroke": {
+                "color": "ink",
+                "width": 1.5,
+                "cap": "round",
+                "join": "round"
+              }
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "check",
+      "type": "path",
+      "d": "M7 10L9.2 12.2L13 8",
+      "pivot": [10, 10],
+      "scale": 0,
+      "stroke": {
+        "color": "accent",
+        "width": 1.5,
+        "cap": "round",
+        "join": "round"
+      }
+    }
+  ],
+  "timelines": {
+    "turn": {
+      "duration": 1.2,
+      "loop": "loop",
+      "reducedMotion": "skip",
+      "tracks": {
+        "arrows.rotate": [
+          [0, 0],
+          [1.2, 360]
+        ]
+      },
+      "quantize": 10
+    },
+    "pop": {
+      "duration": 0.6,
+      "reducedMotion": "end",
+      "tracks": {
+        "check.scale": [
+          [0, 0, "elastic(1, 0.3)"],
+          [0.6, 1]
+        ]
+      }
+    },
+    "peek-motion": {
+      "duration": 0.4,
+      "reducedMotion": "end",
+      "tracks": {
+        "peek.scale": [
+          [0, 1],
+          [0.4, 1.1]
+        ]
+      }
+    },
+    "wait": {
+      "duration": 1.2,
+      "loop": "loop",
+      "reducedMotion": "skip",
+      "tracks": {
+        "check.scale": [
+          [0, 0],
+          [1.2, 0]
+        ]
+      },
+      "quantize": 10
+    }
+  },
+  "machine": {
+    "layers": {
+      "hover": {
+        "initial": "rest",
+        "states": {
+          "rest": {
+            "play": "peek-motion",
+            "on": [
+              {
+                "when": "hover",
+                "to": "forward",
+                "sync": true
+              }
+            ],
+            "hold": true
+          },
+          "forward": {
+            "play": "peek-motion",
+            "on": [
+              {
+                "when": "!hover",
+                "to": "reverse",
+                "sync": true
+              }
+            ]
+          },
+          "reverse": {
+            "play": "peek-motion",
+            "speed": -1,
+            "on": [
+              {
+                "when": "hover",
+                "to": "forward",
+                "sync": true
+              }
+            ]
+          }
+        }
+      },
+      "rotation": {
+        "initial": "idle",
+        "states": {
+          "idle": {
+            "play": "turn",
+            "on": [
+              {
+                "when": "syncing",
+                "to": "spin"
+              }
+            ],
+            "time": "phase * 1.2"
+          },
+          "spin": {
+            "play": "turn",
+            "on": [
+              {
+                "when": "!syncing",
+                "to": "idle",
+                "sync": true,
+                "exitNext": "step"
+              }
+            ]
+          }
+        }
+      },
+      "completion": {
+        "initial": "idle",
+        "states": {
+          "idle": {
+            "play": "wait",
+            "on": [
+              {
+                "when": "syncing",
+                "to": "running"
+              }
+            ],
+            "time": "phase * 1.2"
+          },
+          "running": {
+            "play": "wait",
+            "on": [
+              {
+                "when": "!syncing",
+                "to": "done",
+                "exitNext": "step"
+              }
+            ]
+          },
+          "done": {
+            "play": "pop",
+            "on": [
+              {
+                "when": "syncing",
+                "to": "running"
+              }
+            ]
+          }
+        }
+      }
+    }
+  },
+  "listeners": [
+    {
+      "on": "enter",
+      "set": {
+        "hover": true
+      }
+    },
+    {
+      "on": "leave",
+      "set": {
+        "hover": false
+      }
+    }
+  ]
+}

package/modules/motion/examples/sync.animl

@@ -0,0 +1,64 @@
+<anima version="0.1" name="sync" title="Sync" grid="20" requires="motion bind">
+  <color name="ink" value="#141413"/>
+  <color name="accent" value="#d97757"/>
+  <bool name="syncing"/>
+  <bool name="hover"/>
+  <number name="phase" default="0" min="0" max="1"/>
+  <a11y role="button" label="Sync" activate="syncing" pressed="syncing"/>
+  <hit rect="0 0 20 20"/>
+  <group id="peek" pivot="10 10">
+    <group id="arrows" pivot="10 10">
+      <arc id="top" cx="10" cy="10" r="6" from="-165" to="-15" stroke="ink" stroke-width="1.5" stroke-linecap="round"/>
+      <path id="top-tip" d="M14.064 7.447L15.796 8.447L16.796 6.715" stroke="ink" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+      <arc id="bottom" cx="10" cy="10" r="6" from="15" to="165" stroke="ink" stroke-width="1.5" stroke-linecap="round"/>
+      <path id="bottom-tip" d="M5.936 12.553L4.204 11.553L3.204 13.285" stroke="ink" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+    </group>
+  </group>
+  <path id="check" d="M7 10L9.2 12.2L13 8" pivot="10 10" scale="0" stroke="accent" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+
+  <timeline name="turn" duration="1.2" loop="loop" reducedMotion="skip" quantize="10">
+    <track target="arrows.rotate">0 0; 1.2 360</track>
+  </timeline>
+  <timeline name="pop" duration="0.6" reducedMotion="end">
+    <track target="check.scale">0 0 elastic(1, 0.3); 0.6 1</track>
+  </timeline>
+  <timeline name="peek-motion" duration="0.4" reducedMotion="end">
+    <track target="peek.scale">0 1; 0.4 1.1</track>
+  </timeline>
+  <layer name="hover" initial="rest">
+    <state name="rest" play="peek-motion" hold="true">
+      <on when="hover" to="forward" sync="true"/>
+    </state>
+    <state name="forward" play="peek-motion">
+      <on when="!hover" to="reverse" sync="true"/>
+    </state>
+    <state name="reverse" play="peek-motion" speed="-1">
+      <on when="hover" to="forward" sync="true"/>
+    </state>
+  </layer>
+  <listener on="enter" set="hover=true"/>
+  <listener on="leave" set="hover=false"/>
+  <layer name="rotation" initial="idle">
+    <state name="idle" play="turn" time="phase * 1.2">
+      <on when="syncing" to="spin"/>
+    </state>
+    <state name="spin" play="turn">
+      <on when="!syncing" to="idle" sync="true" exitNext="step"/>
+    </state>
+  </layer>
+  <!-- The completion clock uses the same phase and step grid as rotation. -->
+  <timeline name="wait" duration="1.2" loop="loop" reducedMotion="skip" quantize="10">
+    <track target="check.scale">0 0; 1.2 0</track>
+  </timeline>
+  <layer name="completion" initial="idle">
+    <state name="idle" play="wait" time="phase * 1.2">
+      <on when="syncing" to="running"/>
+    </state>
+    <state name="running" play="wait">
+      <on when="!syncing" to="done" exitNext="step"/>
+    </state>
+    <state name="done" play="pop">
+      <on when="syncing" to="running"/>
+    </state>
+  </layer>
+</anima>

package/modules/motion/examples/verify.py

@@ -0,0 +1,71 @@
+"""CLI-only acceptance proof; independently expected scalars, no player imports.
+Run from any directory: python modules/motion/examples/verify.py
+JSONL evidence is regenerated only after all assertions succeed.
+"""
+import json
+import math
+from pathlib import Path
+import subprocess
+
+HERE = Path(__file__).resolve().parent
+ROOT = HERE.parents[2]
+CLI = ['node', str(ROOT / 'packages/cli/src/main.ts')]
+
+def cli(*args):
+    return subprocess.run(CLI + list(map(str, args)), cwd=ROOT, text=True,
+                          capture_output=True, check=True).stdout
+
+def near(actual, expected):
+    assert math.isclose(actual, expected, abs_tol=1e-8), (actual, expected)
+
+def column(rows, address, expected):
+    assert len(rows) == len(expected), (address, len(rows), len(expected))
+    for row, value in zip(rows, expected):
+        near(row['values'][address], value)
+
+built = cli('build', HERE / 'sync.animl')
+assert json.loads(built) == json.loads((HERE / 'sync.ani').read_text())
+for ext in ['animl', 'ani']:
+    cli('validate', HERE / ('sync.' + ext))
+results = {}
+for script in sorted((HERE / 'scripts').glob('*.txt')):
+    text = cli('sample', HERE / 'sync.ani', '--script', script)
+    rows = [json.loads(line) for line in text.splitlines()]
+    results[script.stem] = (text, rows)
+
+def rows(name):
+    return results[name][1]
+
+column(rows('spin'), 'arrows.rotate', [0, 0, 30, 330, 0, 30])
+column(rows('sweep')[:13], 'arrows.rotate', [0] + list(range(30, 360, 30)) + [0])
+column(rows('sweep')[13:], 'arrows.rotate', [0] + list(range(0, 360, 30)))
+column(rows('stop'), 'arrows.rotate', [90, 90, 90, 120, 120, 120, 120, 180, 0, 30])
+column(rows('stop'), 'check.scale', [0, 0, 0, 0, 1 + math.sqrt(2)/4, 1, 1, 1, 0, 0])
+assert [row['states']['rotation'] for row in rows('stop')[:4]] == ['spin', 'spin', 'spin', 'idle']
+assert rows('stop')[6]['settled']
+column(rows('hover'), 'peek.scale', [1.05, 1.05, 1.025, 1.025, 1.05, 1, 1.1, 1])
+assert rows('hover')[5]['settled'] and rows('hover')[-1]['settled']
+column(rows('phase'), 'arrows.rotate', [0, 0, 30, 60, 180, 330, 0, 0, 30])
+column(rows('reduced'), 'arrows.rotate', [0] * 6)
+column(rows('reduced'), 'check.scale', [0, 0, 0, 1, 1, 1])
+assert all(row['settled'] for row in rows('reduced'))
+column(rows('rest'), 'arrows.rotate', [0])
+column(rows('rest'), 'peek.scale', [1])
+column(rows('rest'), 'check.scale', [0])
+# Geometry checks complement rest-state samples; the paths use the brief's exact check tips.
+doc = json.loads(built)
+assert doc['grid'] == 20 and doc['colors'] == {'ink': '#141413', 'accent': '#d97757'}
+peek, check = doc['nodes']
+assert peek['pivot'] == [10, 10] and check['pivot'] == [10, 10]
+assert check['d'] == 'M7 10L9.2 12.2L13 8'
+arrows = peek['children'][0]
+assert arrows['pivot'] == [10, 10]
+for arc, angles in zip(arrows['children'][::2], [(-165, -15), (15, 165)]):
+    assert arc['center'] == [10, 10] and arc['r'] == 6
+    assert (arc['from'], arc['to']) == angles
+    assert arc['stroke']['width'] == 1.5 and arc['stroke']['cap'] == 'round'
+for name, (text, _) in results.items():
+    (HERE / 'evidence' / (name + '.jsonl')).write_text(text)
+print('sync example: 6/6 items; 7 sample scripts,', sum(len(r) for _, r in results.values()), 'snapshots')
+print('1: twelve ticks/loop; 2: next tick + held angle + elastic pop; 3: reversible peek/turnaround')
+print('4: quantized input scrub; 5: reduced still/instant check; 6: rest arrows only')

package/modules/motion/manifest.source

@@ -0,0 +1,67 @@
+// Motion depends on the base player only; its own browser runtime is capped at 8 KiB.
+export const after: string[] = [];
+export default {
+  ...{
+    name: 'motion',
+    summary:
+      'Timeline control: play, pause, seek, scrub, reverse, work areas, loop overrides and quantized playback.',
+    after: [],
+    core: { entry: 'core/index.ts', export: 'motion', svg: 'core/svg.ts', svgExport: 'motionSVG' },
+    web: [{ name: 'motion', budget: 6528 }],
+    adapters: {
+      'packages/core/src/modules/motion/index.ts': 'core/index.ts',
+      'packages/core/src/modules/motion/svg.ts': 'core/svg.ts',
+      'packages/markup/src/motion.ts': 'markup/index.ts',
+      'packages/web/src/motion.ts': 'web/index.ts',
+    },
+    exports: {
+      'core:./motion': 'packages/core/src/modules/motion/index.ts',
+      'markup:./motion': 'packages/markup/src/motion.ts',
+      'web:./motion': 'packages/web/src/motion.ts',
+    },
+    markupHook: {
+      slot: 'motionCompiler',
+      type: 'motionMarkup',
+      value: 'motionMarkup',
+      browserName: 'motion',
+    },
+    tests: [
+      'modules/motion/test/**/*.test.ts',
+      'packages/markup/test/corpus.test.ts',
+      'packages/markup/test/names.test.ts',
+      'packages/markup/test/compile.test.ts',
+      'packages/markup/test/decompile.test.ts',
+      'packages/markup/test/format.test.ts',
+    ],
+    conformance: [
+      'motion-',
+      'reduced-motion',
+      'animation-cubic-value',
+      'animation-elastic-in',
+      'animation-elastic-in-out',
+      'animation-host-loop-override',
+      'animation-host-play-pause-stop',
+      'animation-keys-reference',
+      'animation-keys-signed-integer',
+      'animation-keys-string',
+      'animation-keys-unsigned-integer',
+      'animation-mix-discrete',
+      'animation-mix-numeric',
+      'animation-quantized-playback',
+      'animation-reverse',
+      'animation-seek',
+      'animation-work-area',
+      'host-api-animation-metadata',
+      'host-api-low-level-animation',
+      'host-api-low-level-scene-query',
+      'host-api-multi-state-machine',
+      'host-api-scrub',
+      'state-machine-exit-time-seconds',
+      'transforms-origin-animation',
+      'data-bind-keyframes',
+      'data-bind-keyframes-blend',
+    ],
+    docs: ['spec/SPEC.md', 'spec/ANIML.md', 'docs/WEB.md'],
+  },
+  after,
+};

package/modules/nested/SPEC.md

@@ -0,0 +1,79 @@
+# Nested component controls
+
+Declare `components nested`; expressions require `bind`, and `$` paths require `data`.
+The optional module preserves ordinary components' byte budget. It adds the following fields
+(JSON and AniML use the same names):
+
+| JSON field | AniML | Meaning |
+|---|---|---|
+| `time: number \| string` | `time="0.5"` or `time="$t"` | Absolute child animation source time in seconds |
+| `fps: number` | `fps="12"` | Positive finite sample rate |
+| `size: [w,h]` | `size="20 10"` | Positive target bounds |
+| `fit: string` | `fit="contain"` | contain, cover, fill, none, scale-down, fit-width, fit-height |
+| `align: string` | `align="bottom-right"` | center, top-left, top, top-right, left, right, bottom-left, bottom, bottom-right |
+| `outputs: {done: expression}` | `<output name="done" value="count > 1"/>` inside a component | Read-only number, bool, color or string outputs |
+| `component: "$card"` | `component="$card"` | Select the definition named by a component data property |
+
+`time` is sampled after parent bindings and before the child step. Omitted time accumulates
+`dt * speed`, preserving the fractional remainder between samples. With `fps`, the source clock
+is floored to `floor(time * fps) / fps`, recognizing a tick reached within SPEC §5's existing
+1e-9 second boundary rule. Time must be finite and nonnegative; invalid live values throw
+`instance-time` with a node pointer and corrective hint. Backward scrubbing resamples the current
+child state without reconstructing it or undoing transitions. State ages and fades advance by
+positive source deltas; animation sampling and event crossings follow both directions. When
+`motion` is also declared its timeline work areas, speeds and looping remain in effect.
+Paused children retain their time, pending writes and fractional accumulator.
+
+Fitting maps the child's entire viewBox, including its nonzero origin, into `[0,0,w,h]`.
+With size present, omitted fit defaults to contain and omitted alignment to center.
+Contain uses the smaller scale, cover the larger, fill separate X/Y scales, none 1, scale-down
+min(1,contain), and the axis fits use that axis's scale. Remaining space aligns to the selected
+edge or center. There is no implicit viewport clip. Ordinary instance transforms compose outside
+the fit. Hit testing uses the inverse fitted world matrix. `fit`/`align` without `size`, or a zero
+size, is `instance-size`. With lists, ordinary repeated placements keep their existing bounds
+semantics; the new fit applies to instance nodes.
+
+An output expression reads the child's inputs, `$` properties and nested child outputs. Outputs
+cannot depend on their own `outputs.*` namespace. Invalid expressions are `output-expression`;
+opaque list/model sources also fail with `output-expression`. Parent reads use `badge.outputs.done`, including in bindings
+and guards; selected snapshots use `badge/outputs.done`. The parent evaluates before children,
+so child writes from this step reach parent bindings/guards on the next step. A changed output
+keeps the parent awake for that next pass, including when the child is otherwise settled. Outputs are
+read-only: actions, bindings, poses, tracks and host writes reject with `read-only-path`.
+Repeat items expose the same outputs as `rows.0.outputs.done`; snapshots use
+`rows/0/outputs.done`. Read access is installed for every player, including repeated components.
+Canonical decompilation may use a JSON-valued `outputs` attribute, which round-trips identically.
+
+The `data` property type `component` stores a definition name, defaults to empty string, and
+validates declared names. Empty selection hides and stops a placement. Changing names rebuilds
+that placement with default state; retaining a name keeps its player. Clearing then restoring a
+name rebuilds it. Unrelated placements/repeat identities survive. Runtime values must name a
+declared component or empty string. Dynamic choices with a shared input name must agree on its
+type (`component-input-type`), and explicit initializers must exist in every choice
+(`unknown-input`). A non-component `$` selector is `component-path`. All possible choices are
+validated, including recursion/expansion limits. With `data components nested`, `$card == component("row")` and `!=` compare a component
+property to a declared component definition. Typed literal functions are compiled through the
+model's optional core guard hook; numeric bind functions are unchanged. Strings, unknown names,
+and ordering operators fail with `guard-literal` at the transition's `/when` pointer and a hint.
+These guards do not require `bind`. An empty property is unequal to every declared definition.
+
+Drawing uses per-player trees, recycles released slots, and shares the existing SVG and Canvas
+backends. This follows [graph research](../../docs/research/rive-format-and-graph.md) §6; the single
+parent/child step ordering follows [state research](../../docs/research/rive-animation-and-state.md)
+§C. No native implementation is copied.
+
+Native observation: Rive 1.9.1 reports x=1 then x=2 after 0.12s and 0.13s with nested quantize=12
+for x=12t. Anima reports x=1 then x=3. A nonboundary 0.12s+0.14s follow-up matches x=1 then x=3
+in both runtimes. This supports a precision-boundary explanation (an inference), not per-step
+truncation. The original delta1 observation remains a finding with unchanged numbers and limits.
+
+
+P5b-8 precision follow-up: fresh captures in `oracle/p5b8/` reproduce the native .25s miss with
+one advance and with .12+.13, .125+.125, .2+.05 and .1+.15. A parallel unquantized child reads x=3
+at .25 while its quantized twin reads2; .2500001 reads3.00000095/3. At fps12.0000001, native still
+reads2 (that rate rounds to12 in float32); fps12.000001 reads2.99999976. The latter rate is
+12.000000953674316 in float32; 36 divided by that rate is2.99999976158144. This identifies native
+precision/rounding as the source of the boundary disagreement, not per-call truncation or an
+Anima frame-rule error. The exact internal native accumulator/comparison routine remains
+unverified from black-box captures. Anima retains the decided absolute 1e-9-second rule and
+its original x=3 versus native2 delta1 finding, without changing reference values or tolerances.

package/modules/nested/capabilities/components-leaf-fit/example.ani

@@ -0,0 +1,50 @@
+{
+  "anima": "0.1",
+  "name": "components-leaf-fit",
+  "grid": 20,
+  "requires": ["components", "nested", "bind"],
+  "nodes": [
+    {
+      "id": "badge",
+      "type": "instance",
+      "component": "row",
+      "size": [20, 10],
+      "fit": "contain",
+      "align": "right"
+    }
+  ],
+  "components": {
+    "row": {
+      "grid": 10,
+      "viewBox": [-5, -5, 10, 10],
+      "inputs": {
+        "count": {
+          "type": "number",
+          "default": 2
+        }
+      },
+      "nodes": [
+        {
+          "id": "dot",
+          "type": "circle",
+          "center": [0, 0],
+          "r": 2,
+          "fill": {
+            "color": "#000"
+          }
+        }
+      ],
+      "listeners": [
+        {
+          "on": "click",
+          "set": {
+            "count": 1
+          }
+        }
+      ],
+      "bind": {
+        "dot.r": "count"
+      }
+    }
+  }
+}

package/modules/nested/capabilities/components-leaf-fit/example.animl

@@ -0,0 +1,9 @@
+<anima version="0.1" name="components-leaf-fit" grid="20" requires="components nested bind">
+  <component name="row" grid="10" viewBox="-5 -5 10 10">
+    <number name="count" default="2"/>
+    <circle id="dot" cx="0" cy="0" r="2" fill="#000"/>
+    <bind target="dot.r" value="count"/>
+    <listener on="click" set="count=1"/>
+  </component>
+  <instance id="badge" component="row" size="20 10" fit="contain" align="right"/>
+</anima>

package/modules/nested/capabilities/components-nested-quantize/example.ani

@@ -0,0 +1,65 @@
+{
+  "anima": "0.1",
+  "name": "components-nested-quantize",
+  "grid": 20,
+  "requires": ["components", "nested", "bind", "data"],
+  "nodes": [
+    {
+      "id": "badge",
+      "type": "instance",
+      "component": "row",
+      "fps": 12
+    }
+  ],
+  "components": {
+    "row": {
+      "grid": 10,
+      "nodes": [
+        {
+          "id": "dot",
+          "type": "circle",
+          "center": [5, 5],
+          "r": 1,
+          "fill": {
+            "color": "#000"
+          }
+        }
+      ],
+      "timelines": {
+        "go": {
+          "duration": 1,
+          "tracks": {
+            "dot.x": [
+              [0, 0],
+              [1, 12]
+            ]
+          }
+        }
+      },
+      "machine": {
+        "layers": {
+          "main": {
+            "initial": "go",
+            "states": {
+              "go": {
+                "play": "go"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "data": {
+    "models": {
+      "Clock": {
+        "properties": {
+          "t": {
+            "type": "number",
+            "default": 0.5
+          }
+        }
+      }
+    }
+  }
+}