animl-cli 0.0.0-stage → 0.1.0

package/modules/data/manifest.source

@@ -0,0 +1,111 @@
+export const after = ['components', 'bind', 'events', 'input', 'focus', 'paint'];
+export default {
+  ...{
+    name: 'data',
+    summary:
+      'Data: typed view models, $ paths, named instances, lists of models and two-way binding.',
+    after: [],
+    core: { entry: 'core/index.ts', export: 'data' },
+    web: [{ name: 'data', budget: 7040 }],
+    adapters: {
+      'packages/core/src/modules/data/index.ts': 'core/index.ts',
+      'packages/markup/src/data.ts': 'markup/index.ts',
+      'packages/web/src/data.ts': 'web/index.ts',
+    },
+    exports: {
+      'core:./data': 'packages/core/src/modules/data/index.ts',
+      'markup:./data': 'packages/markup/src/data.ts',
+      'web:./data': 'packages/web/src/data.ts',
+    },
+    markupHook: {
+      browserName: 'data',
+      slot: 'dataCompiler',
+      type: 'dataMarkup',
+      value: 'dataMarkup',
+    },
+    tests: [
+      'modules/data/test/**/*.test.ts',
+      'packages/markup/test/corpus.test.ts',
+      'packages/markup/test/names.test.ts',
+      'packages/markup/test/decompile.test.ts',
+      'packages/markup/test/compile.test.ts',
+    ],
+    conformance: [
+      'data-bind-conditions',
+      'data-bind-converter-options',
+      'data-bind-instance-values',
+      'data-bind-keyframes',
+      // seam(P7-2): layout owns data.bind-layout and its completed probes.
+      'data-bind-script-inputs',
+      'data-bind-text',
+      'data-binding-absolute',
+      'data-binding-once',
+      'data-binding-relative',
+      'data-binding-to-source',
+      'data-binding-two-way-prefer-source',
+      'data-binding-two-way-prefer-target',
+      'data-component-public-data',
+      'data-custom-property-boolean',
+      'data-custom-property-color',
+      'data-custom-property-enum',
+      'data-custom-property-number',
+      'data-custom-property-string',
+      'data-custom-property-trigger',
+      'data-default-instance',
+      'data-editor-preview-instance',
+      'data-enum-members',
+      'data-global-model',
+      'data-instance-export',
+      'data-list-items',
+      'data-model-definition',
+      'data-named-instances',
+      'data-operation-operand-view-model',
+      'data-property-artboard',
+      'data-property-asset-blob',
+      'data-property-asset-font',
+      'data-property-asset-image',
+      'data-property-boolean',
+      'data-property-color',
+      'data-property-enum-custom',
+      'data-property-enum-system',
+      'data-property-list',
+      'data-property-number',
+      'data-property-string',
+      'data-property-symbol-list-index',
+      'data-property-text-style',
+      'data-property-trigger',
+      'data-property-view-model',
+      'data-script-model-api',
+      'data-scripted-converter',
+      'data-state-action-trigger',
+      'data-system-enum-horizontal-text-align',
+      'data-system-enum-layout-alignment',
+      'data-system-enum-layout-direction',
+      'data-system-enum-layout-display',
+      'data-system-enum-layout-flex-direction',
+      'data-system-enum-layout-position',
+      'data-system-enum-layout-position-units',
+      'data-system-enum-layout-scale-type',
+      'data-system-enum-layout-wrap',
+      'data-system-enum-scroll-direction',
+      'data-system-enum-semantic-check-state',
+      'data-system-enum-text-box',
+      'data-system-enum-text-overflow',
+      'data-system-enum-text-trim-bottom',
+      'data-system-enum-text-trim-top',
+      'data-system-enum-vertical-text-align',
+      'data-system-enum-word-wrap',
+      'drawing-paint-gradient-channel-binding',
+      'input-data-listener',
+      'input-write-data-constant',
+      'input-write-data-copy',
+      'input-write-focused',
+      'input-write-gamepad-axis',
+      'input-write-gamepad-button-pressed',
+      'input-write-gamepad-button-value',
+      'input-write-gamepad-changed-value',
+    ],
+    docs: ['spec/SPEC.md', 'spec/ANIML.md', 'modules/data/SPEC.md'],
+  },
+  after,
+};

package/modules/data-artboard/SPEC.md

@@ -0,0 +1,94 @@
+# Bindable artboards (`dataartboard`)
+
+This optional entry adds `artboard` as a source spelling for a component-valued model
+property. It compiles to the existing component data representation; empty string
+clears the placement. Declare `data`, `components`, `nested`, `host`, and
+`dataartboard` in `requires`. Bind an instance with `component="$content"`.
+AniML spells a model property `<artboard name="content" default="front"/>`; JSON
+spells it `{ "type": "artboard", "default": "front" }`. Browser authoring imports
+`markup-data-artboard` after the runtime entries (it includes the complete authoring hooks).
+
+`player.data.artboard(path)` returns a queued typed handle. Strings name local
+components. `icon.component(loadedModel, name)` (also the core `component` helper)
+produces a value for a component in another successfully loaded document. External
+values retain the source's lexical component definitions. An empty slot can receive
+an external component without any authored local definitions. Assignments instantiate
+fresh players; assigning the same component preserves the current instance.
+Animation clocks restart when the selection changes. The existing `data` placement
+and list-item context rules apply. The host data getter exposes an opaque internal
+string for an external component; callers should retain the assignable value.
+
+Wrong property types use `data-type`. Invalid selections use `unknown-component`;
+an external value lacking its loaded document uses `artboard-document`. Each has
+a JSON pointer and a repair hint. Recursive host assignments exceeding eight active
+component levels use `limit-exceeded`. External selections cannot introduce new scoped
+input names into an already loaded parent; use the common authored interface.
+
+The implementation reuses Anima's nested-player machinery rather than a native
+runtime algorithm. See `docs/research/rive-format-and-graph.md` (lexical graph
+references), `docs/research/rive-animation-and-state.md` (instance state and update
+order), and `docs/research/rive-web-runtime.md` (host ownership). No native source
+or binary format is used.
+
+
+## Browser resource ownership
+
+Import `@anima-format/web/data-artboard` for browser values. Its smaller
+`data-artboard-values` entry provides only the core value/selection API; the full
+entry includes that entry and the resource bridge. Both entry load orders are safe.
+The split keeps the existing artboard entry's byte ceiling; neither entry adds a
+runtime dependency.
+
+Acquire browser values using `icon.component(source.player.model, name)` after the
+source's `ready` promise resolves. A source player's model identifies its resource
+load even when two hosts share the same compiled declarations. Values capture that
+load's resolved image records (absolute sources, intrinsic dimensions, self-contained
+Blob data) and decoded font faces, including unused component definitions and nested
+placements. They retain lexical component definitions without retaining the source
+host's resolver. The destination does not re-resolve those resources using its own
+resolver, base URL or same-named assets. A destination may have no authored assets.
+
+The destination installs resources on each selected child player. Fonts retain their
+own references in the browser font set; image records are scoped to the instance.
+Sibling destinations and host loads remain isolated. Reloading or destroying a source
+does not mutate an acquired value. Clearing/replacing a selection releases the old
+instance's font references on the next destination draw; destination cleanup releases
+all adopted faces. A retained value can be assigned again after every source and
+previous destination releases its faces. Retired image slots are ignored during the
+retained SVG refresh. SVG and canvas consume the same adopted records and text layout.
+
+## Cross-document model contract
+
+For an external selection, an artboard property's optional `model` names its expected
+model in the destination data document (JSON `model: "Card"`, AniML `model="Card"`).
+Otherwise inherited source data uses the placement's explicit `data` instance model,
+or the parent's default model. A component with its own independent data keeps it
+unless the placement supplies data; an explicit property model still checks its
+contract.
+
+Before rebinding a selected external child, the schemas must be structurally
+compatible: the destination supplies every source property with the same scalar
+kind, asset kind, numeric bounds and enum members (enum order does not matter).
+Model references and list element models are checked recursively. Matching named
+instances that the placement shares (including globals) are checked as well, so a
+source binding cannot silently consume a differently typed destination instance. Destination-only
+properties and different default values are allowed. Document-local component and
+text-style names are not schema identities. Model names may differ when their
+structures match; no model/property-name remapping is performed.
+
+An incompatible or absent required model throws `artboard-model` during the step
+that instantiates the queued selection. The diagnostic points to `/data/` plus the
+escaped bound property path, explains the incompatible placement model, and hints
+at matching property types, enum members and referenced models. It happens before
+binding the source instance to the destination's data. The previously selected
+child is not replaced. Correct the selection before stepping again. Generic host
+metadata continues to report the component storage alias for source-spelled artboards.
+
+
+## External assignment lifetime
+
+External aliases are validated against the owning player's assignment map; they never extend a
+shared compiled property schema. After a step, assignments remain retained only while queued or
+referenced by current data in the owning player or its collected descendants. Replacing or clearing
+an external selection releases retired assignments and their model/catalog/resource snapshots;
+clearing also removes the selected child player. Duplicate queued writes retain independent references across step boundaries, and pruning also runs when the nesting factory declines. Retired aliases are never recycled for a different assignment. A retained external value may be assigned again.

package/modules/data-artboard/capabilities/components-host-artboard-reference/example.ani

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

package/modules/data-artboard/capabilities/components-host-artboard-reference/example.animl

@@ -0,0 +1,26 @@
+<anima version="0.1" name="swappable-card" grid="20" requires="components data bind nested host dataartboard lists">
+  <component name="front" grid="20">
+    <circle id="dot" cx="5" cy="5" r="1" fill="#f00"/>
+    <bind target="dot.r" value="$radius"/>
+  </component>
+  <component name="back" grid="20">
+    <rect id="box" x0="1" y0="1" width="3" height="4" fill="#00f"/>
+    <bind target="box.width" value="$radius + 1"/>
+  </component>
+  <component name="row" grid="20" data="Cell">
+    <instance id="body" component="$content"/>
+  </component>
+
+  <repeat id="rows" list="$items" component="&quot;row&quot;" dx="10"/>
+
+  <model name="Card">
+    <list name="items" of="Cell"/>
+  </model>
+  <model name="Cell">
+    <artboard name="content" default="&quot;front&quot;"/>
+    <number name="radius" default="2"/>
+  </model>
+  <instance name="main" model="Card" default="true">
+    <set path="items" value="[{&quot;radius&quot;:3},{&quot;radius&quot;:5}]"/>
+  </instance>
+</anima>

package/modules/data-artboard/capabilities/data-host-artboard/example.ani

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

package/modules/data-artboard/capabilities/data-host-artboard/example.animl

@@ -0,0 +1,18 @@
+<anima version="0.1" name="swappable-card" grid="20" requires="components data bind nested host dataartboard">
+  <component name="front" grid="20">
+    <circle id="dot" cx="5" cy="5" r="1" fill="#f00"/>
+    <bind target="dot.r" value="$radius"/>
+  </component>
+  <component name="back" grid="20">
+    <rect id="box" x0="1" y0="1" width="3" height="4" fill="#00f"/>
+    <bind target="box.width" value="$radius + 1"/>
+  </component>
+
+  <instance id="content" component="$content"/>
+
+  <model name="Card">
+    <artboard name="content" default="&quot;front&quot;"/>
+    <number name="radius" default="2"/>
+  </model>
+  <instance name="main" model="Card" default="true"/>
+</anima>

package/modules/data-artboard/capabilities/host-api-bindable-artboards/example.ani

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

package/modules/data-artboard/capabilities/host-api-bindable-artboards/example.animl

@@ -0,0 +1,34 @@
+<anima version="0.1" name="swappable-card" grid="20" requires="components data bind nested host dataartboard">
+  <component name="front" grid="20">
+    <circle id="dot" cx="5" cy="5" r="1" fill="#000"/>
+    <timeline name="move" duration="1">
+      <track target="dot.x">
+        0  0
+        1  10
+      </track>
+    </timeline>
+    <layer name="move" initial="moving">
+      <state name="moving" play="move"/>
+    </layer>
+  </component>
+  <component name="back" grid="20">
+    <circle id="box" cx="5" cy="5" r="1" fill="#000"/>
+    <timeline name="move" duration="1">
+      <track target="box.x">
+        0  20
+        1  30
+      </track>
+    </timeline>
+    <layer name="move" initial="moving">
+      <state name="moving" play="move"/>
+    </layer>
+  </component>
+
+  <instance id="content" component="$content"/>
+
+  <model name="Card">
+    <artboard name="content" default="&quot;front&quot;"/>
+    <number name="radius" default="2"/>
+  </model>
+  <instance name="main" model="Card" default="true"/>
+</anima>

package/modules/data-artboard/capabilities/host-api-data-artboard/example.ani

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

package/modules/data-artboard/capabilities/host-api-data-artboard/example.animl

@@ -0,0 +1,18 @@
+<anima version="0.1" name="swappable-card" grid="20" requires="components data bind nested host dataartboard">
+  <component name="front" grid="20">
+    <circle id="dot" cx="5" cy="5" r="1" fill="#f00"/>
+    <bind target="dot.r" value="$radius"/>
+  </component>
+  <component name="back" grid="20">
+    <rect id="box" x0="1" y0="1" width="3" height="4" fill="#00f"/>
+    <bind target="box.width" value="$radius + 1"/>
+  </component>
+
+  <instance id="content" component="$content"/>
+
+  <model name="Card">
+    <artboard name="content" default="&quot;front&quot;"/>
+    <number name="radius" default="2"/>
+  </model>
+  <instance name="main" model="Card" default="true"/>
+</anima>

package/modules/data-artboard/manifest.source

@@ -0,0 +1,41 @@
+export const after = ['nested', 'host'];
+export default {
+  name: 'data-artboard',
+  summary:
+    'Data: component-valued model properties (choose which component an instance shows from data).',
+  after,
+  core: { entry: 'core/index.ts', export: 'dataArtboard' },
+  web: [
+    { name: 'data-artboard', budget: 1024, over: 'data-artboard-values' },
+    { name: 'data-artboard-values', budget: 1536, over: 'nested' },
+    { name: 'markup-data-artboard', budget: 256, authoring: true, over: 'markup-hooks' },
+  ],
+  adapters: {
+    'packages/core/src/modules/data-artboard/index.ts': 'core/index.ts',
+    'packages/web/src/data-artboard.ts': 'web/index.ts',
+    'packages/web/src/dataartboard.ts': 'web/index.ts',
+    'packages/web/src/data-artboard-values.ts': 'web/values.ts',
+    'packages/web/src/markup-data-artboard.ts': 'web/markup.ts',
+    'packages/markup/src/data-artboard.ts': 'markup/index.ts',
+  },
+  exports: {
+    'core:./data-artboard': 'packages/core/src/modules/data-artboard/index.ts',
+    'web:./data-artboard': 'packages/web/src/data-artboard.ts',
+    'web:./dataartboard': 'packages/web/src/dataartboard.ts',
+    'web:./data-artboard-values': 'packages/web/src/data-artboard-values.ts',
+    'web:./markup-data-artboard': 'packages/web/src/markup-data-artboard.ts',
+    'markup:./data-artboard': 'packages/markup/src/data-artboard.ts',
+  },
+  tests: [
+    'modules/data-artboard/test/**/*.test.ts',
+    'packages/markup/test/corpus.test.ts',
+    'packages/markup/test/names.test.ts',
+  ],
+  conformance: [
+    'data-host-artboard',
+    'host-api-bindable-artboards',
+    'host-api-data-artboard',
+    'components-host-artboard-reference',
+  ],
+  docs: ['modules/data-artboard/SPEC.md'],
+};

package/modules/data-host/SPEC.md

@@ -0,0 +1,50 @@
+# Data and host inspection
+
+`data-host` is the optional browser/package entry; its document feature name is `datahost`
+(the runtime feature-name grammar permits letters only). It imports no other optional entries.
+Host model access requires `host` and `data`; image binding literals additionally require `assets`
+and `bind`. Geometry inspection is pure, does not step the player, and works without data models.
+
+`player.computed(id)` returns a detached, recursively frozen snapshot `{local, root, world, bounds, opacity}`.
+`local` and `root` each expose `{x, y, rotation, scaleX, scaleY}` from the resolved
+node-to-parent and node-to-root affine matrices respectively. Position is the transformed origin
+(including pivot translation), rotation is degrees in [-180, 180], scaleX is the nonnegative first
+column length and scaleY is determinant / scaleX (preserving reflection). If scaleX is zero,
+scaleY is the second column length; atan2 defines rotation, including the all-zero matrix.
+Under skew these are the rotation/scale part of a QR decomposition; they do not encode shear.
+Root space is this Player’s document space, excluding host CSS and any embedding component fit.
+`world` is the six-number node-to-root affine matrix. `opacity` multiplies the resolved node and
+ancestor opacities. `bounds` is a root-space geometric axis-aligned box including descendants;
+it excludes strokes, clips, masks, visibility, effects and layout. Circles are analytic, rectangles
+use transformed corners, paths solve cubic derivative extrema after transforming their normalized control points. Empty geometry has zero bounds at its origin.
+Unknown ids throw `data-path` at `/data/<id>` with a hint. Inspection has no timing effects.
+
+`data.at(path)` resolves the declared type and returns the corresponding live handle with a
+discriminating `type` field. TypeScript callers narrow `handle.type` before a typed write (for
+example, `if (handle.type === "string") handle.set("Grace")`).
+Paths allow optional `$`, named `$instance:property`, nested models and indexed lists, with the
+same validation, retained-handle rebinding and queued writes as the typed accessors. `color(path)`
+already supports nested models; `host-edit` adds `.rgba` and `.hex`. `component(path).set(name)`
+selects a declared component by its definition name; unknown names fail `data-type`.
+`exportedInstances()` returns detached authored instance records with `exported: true` only,
+including private-to-default-model types; dynamically created records are not authored exports.
+`data.batch(fn)` queues every write, coalesces wakeups, and subscriptions run once per changed
+handle after the complete step. Throwing does not roll back writes. Steps within a batch are errors.
+
+With `datahost`, bindings accept `asset("name")` as a validated string literal, including inside
+comparisons and `mix`-independent conditional boolean expressions. Undeclared names report
+`unknown-asset` at the binding JSON pointer with a declaration hint. Quoted text is opaque.
+The ordinary bind type rules apply. Both JSON `bind` and AniML `<bind>` use the same expressions.
+
+`icon.src` reflects the `src` attribute. Setting it follows the existing asynchronous load,
+registration retry, last-request-wins and error lifecycle; an empty value does not load.
+
+Implementation is independent. The host responsibility split follows
+[the web runtime research](../../docs/research/rive-web-runtime.md); no native source is reused.
+
+Image nodes expose discrete string `asset` slots to bindings. JSON `bind: {"pic.asset": {"value": "$photo"}}`
+is AniML `<bind target="pic.asset" value="$photo"/>`. The declared node `asset` remains a valid
+image fallback when a runtime expression returns an unavailable or non-image resource ID.
+URL/Blob host replacements publish generated player-local IDs at the next step, with one
+normal change notification per changed property. Bindings follow that addressed property;
+static consumers without asset bindings retain legacy per-player replacement behavior.

package/modules/data-host/examples/nested.ani

@@ -0,0 +1,82 @@
+{
+  "anima": "0.1",
+  "name": "nested-host",
+  "grid": 20,
+  "requires": ["data", "bind", "datahost"],
+  "nodes": [
+    {
+      "id": "parent",
+      "type": "group",
+      "x": 2,
+      "y": 3,
+      "opacity": 0.5,
+      "children": [
+        {
+          "id": "dot",
+          "type": "circle",
+          "center": [10, 10],
+          "r": 3,
+          "fill": {
+            "color": "#123456"
+          }
+        }
+      ]
+    }
+  ],
+  "bind": {
+    "dot.r": "$a",
+    "dot.fill.color": "$team.lead.tint"
+  },
+  "data": {
+    "models": {
+      "Root": {
+        "properties": {
+          "team": {
+            "type": "model-ref",
+            "model": "Team"
+          },
+          "a": {
+            "type": "number",
+            "default": 3
+          },
+          "b": {
+            "type": "number",
+            "default": 4
+          }
+        }
+      },
+      "Team": {
+        "properties": {
+          "lead": {
+            "type": "model-ref",
+            "model": "Person"
+          }
+        }
+      },
+      "Person": {
+        "properties": {
+          "name": {
+            "type": "string",
+            "default": "Ada"
+          },
+          "tint": {
+            "type": "color",
+            "default": "#123456"
+          }
+        }
+      }
+    },
+    "instances": {
+      "main": {
+        "model": "Root",
+        "default": true,
+        "exported": true,
+        "values": {}
+      },
+      "private": {
+        "model": "Root",
+        "values": {}
+      }
+    }
+  }
+}

package/modules/data-host/examples/nested.animl

@@ -0,0 +1,21 @@
+<anima version="0.1" name="nested-host" grid="20" requires="data bind datahost">
+  <model name="Root">
+    <model-ref name="team" model="Team"/>
+    <number name="a" default="3"/>
+    <number name="b" default="4"/>
+  </model>
+  <model name="Team">
+    <model-ref name="lead" model="Person"/>
+  </model>
+  <model name="Person">
+    <string name="name" default="Ada"/>
+    <color name="tint" default="#123456"/>
+  </model>
+  <instance name="main" model="Root" default="true" export="true"/>
+  <instance name="private" model="Root"/>
+  <group id="parent" x="2" y="3" opacity="0.5">
+    <circle id="dot" cx="10" cy="10" r="3" fill="#123456"/>
+  </group>
+  <bind target="dot.r" value="$a"/>
+  <bind target="dot.fill.color" value="$team.lead.tint"/>
+</anima>

package/modules/data-host/manifest.source

@@ -0,0 +1,26 @@
+export const after = ['host', 'data', 'assets', 'input'];
+export default {
+  name: 'data-host',
+  summary:
+    'Data: read and write page-provided data (nested models, lists, fonts, images) from the host.',
+  after,
+  core: { entry: 'core/index.ts', export: 'dataHost' },
+  web: [{ name: 'data-host', budget: 1088 }],
+  adapters: {
+    'packages/core/src/modules/data-host/index.ts': 'core/index.ts',
+    'packages/web/src/data-host.ts': 'web/index.ts',
+    'packages/web/src/datahost.ts': 'web/index.ts',
+  },
+  exports: {
+    'core:./data-host': 'packages/core/src/modules/data-host/index.ts',
+    'web:./data-host': 'packages/web/src/data-host.ts',
+    'web:./datahost': 'packages/web/src/datahost.ts',
+  },
+  tests: [
+    'modules/data-host/test/**/*.test.ts',
+    'packages/markup/test/corpus.test.ts',
+    'packages/markup/test/names.test.ts',
+  ],
+  conformance: ['data-host', 'transforms-computed-transform-values'],
+  docs: ['modules/data-host/SPEC.md'],
+};