animl-cli 0.0.0-stage → 0.1.1

package/modules/focus/capabilities/input-focus-up/example.ani

@@ -0,0 +1,116 @@
+{
+  "anima": "0.1",
+  "name": "input-focus-up",
+  "grid": 20,
+  "requires": ["focus"],
+  "inputs": {
+    "enabled": {
+      "type": "bool",
+      "default": true
+    }
+  },
+  "nodes": [
+    {
+      "id": "scope",
+      "type": "group",
+      "children": [
+        {
+          "id": "a",
+          "type": "circle",
+          "center": [2, 2],
+          "r": 1,
+          "fill": {
+            "color": "#000"
+          },
+          "focus": {
+            "bounds": [1, 1, 2, 2]
+          }
+        },
+        {
+          "id": "b",
+          "type": "circle",
+          "center": [8, 2],
+          "r": 1,
+          "fill": {
+            "color": "#000"
+          },
+          "focus": {
+            "enabledInput": "enabled",
+            "bounds": [7, 1, 2, 2]
+          }
+        },
+        {
+          "id": "c",
+          "type": "circle",
+          "center": [2, 8],
+          "r": 1,
+          "fill": {
+            "color": "#000"
+          },
+          "focus": {
+            "bounds": [1, 7, 2, 2]
+          }
+        }
+      ],
+      "focus": {
+        "enabled": false,
+        "scope": true,
+        "edge": "stop"
+      }
+    },
+    {
+      "id": "outside",
+      "type": "circle",
+      "center": [15, 2],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      },
+      "focus": {
+        "bounds": [14, 1, 2, 2]
+      }
+    }
+  ],
+  "listeners": [
+    {
+      "on": "focus",
+      "target": "a",
+      "emit": "a-focus"
+    },
+    {
+      "on": "blur",
+      "target": "a",
+      "emit": "a-blur"
+    },
+    {
+      "on": "focus",
+      "target": "b",
+      "emit": "b-focus"
+    },
+    {
+      "on": "blur",
+      "target": "b",
+      "emit": "b-blur"
+    },
+    {
+      "on": "focus",
+      "target": "c",
+      "emit": "c-focus"
+    },
+    {
+      "on": "blur",
+      "target": "c",
+      "emit": "c-blur"
+    },
+    {
+      "on": "focus",
+      "target": "outside",
+      "emit": "outside-focus"
+    },
+    {
+      "on": "blur",
+      "target": "outside",
+      "emit": "outside-blur"
+    }
+  ]
+}

package/modules/focus/capabilities/input-focus-up/example.animl

@@ -0,0 +1,28 @@
+<anima version="0.1" name="input-focus-up" grid="20" requires="focus">
+  <bool name="enabled" default="true"/>
+
+  <group id="scope">
+    <focus enabled="false" scope="true" edge="stop"/>
+    <circle id="a" cx="2" cy="2" r="1" fill="#000">
+      <focus bounds="1 1 2 2"/>
+    </circle>
+    <circle id="b" cx="8" cy="2" r="1" fill="#000">
+      <focus enabled-input="enabled" bounds="7 1 2 2"/>
+    </circle>
+    <circle id="c" cx="2" cy="8" r="1" fill="#000">
+      <focus bounds="1 7 2 2"/>
+    </circle>
+  </group>
+  <circle id="outside" cx="15" cy="2" r="1" fill="#000">
+    <focus bounds="14 1 2 2"/>
+  </circle>
+
+  <listener on="focus" target="a" emit="a-focus"/>
+  <listener on="blur" target="a" emit="a-blur"/>
+  <listener on="focus" target="b" emit="b-focus"/>
+  <listener on="blur" target="b" emit="b-blur"/>
+  <listener on="focus" target="c" emit="c-focus"/>
+  <listener on="blur" target="c" emit="c-blur"/>
+  <listener on="focus" target="outside" emit="outside-focus"/>
+  <listener on="blur" target="outside" emit="outside-blur"/>
+</anima>

package/modules/focus/capabilities/input-listen-blur/example.ani

@@ -0,0 +1,116 @@
+{
+  "anima": "0.1",
+  "name": "input-listen-blur",
+  "grid": 20,
+  "requires": ["focus"],
+  "inputs": {
+    "enabled": {
+      "type": "bool",
+      "default": true
+    }
+  },
+  "nodes": [
+    {
+      "id": "scope",
+      "type": "group",
+      "children": [
+        {
+          "id": "a",
+          "type": "circle",
+          "center": [2, 2],
+          "r": 1,
+          "fill": {
+            "color": "#000"
+          },
+          "focus": {
+            "bounds": [1, 1, 2, 2]
+          }
+        },
+        {
+          "id": "b",
+          "type": "circle",
+          "center": [8, 2],
+          "r": 1,
+          "fill": {
+            "color": "#000"
+          },
+          "focus": {
+            "enabledInput": "enabled",
+            "bounds": [7, 1, 2, 2]
+          }
+        },
+        {
+          "id": "c",
+          "type": "circle",
+          "center": [2, 8],
+          "r": 1,
+          "fill": {
+            "color": "#000"
+          },
+          "focus": {
+            "bounds": [1, 7, 2, 2]
+          }
+        }
+      ],
+      "focus": {
+        "enabled": false,
+        "scope": true,
+        "edge": "stop"
+      }
+    },
+    {
+      "id": "outside",
+      "type": "circle",
+      "center": [15, 2],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      },
+      "focus": {
+        "bounds": [14, 1, 2, 2]
+      }
+    }
+  ],
+  "listeners": [
+    {
+      "on": "focus",
+      "target": "a",
+      "emit": "a-focus"
+    },
+    {
+      "on": "blur",
+      "target": "a",
+      "emit": "a-blur"
+    },
+    {
+      "on": "focus",
+      "target": "b",
+      "emit": "b-focus"
+    },
+    {
+      "on": "blur",
+      "target": "b",
+      "emit": "b-blur"
+    },
+    {
+      "on": "focus",
+      "target": "c",
+      "emit": "c-focus"
+    },
+    {
+      "on": "blur",
+      "target": "c",
+      "emit": "c-blur"
+    },
+    {
+      "on": "focus",
+      "target": "outside",
+      "emit": "outside-focus"
+    },
+    {
+      "on": "blur",
+      "target": "outside",
+      "emit": "outside-blur"
+    }
+  ]
+}

package/modules/focus/capabilities/input-listen-blur/example.animl

@@ -0,0 +1,28 @@
+<anima version="0.1" name="input-listen-blur" grid="20" requires="focus">
+  <bool name="enabled" default="true"/>
+
+  <group id="scope">
+    <focus enabled="false" scope="true" edge="stop"/>
+    <circle id="a" cx="2" cy="2" r="1" fill="#000">
+      <focus bounds="1 1 2 2"/>
+    </circle>
+    <circle id="b" cx="8" cy="2" r="1" fill="#000">
+      <focus enabled-input="enabled" bounds="7 1 2 2"/>
+    </circle>
+    <circle id="c" cx="2" cy="8" r="1" fill="#000">
+      <focus bounds="1 7 2 2"/>
+    </circle>
+  </group>
+  <circle id="outside" cx="15" cy="2" r="1" fill="#000">
+    <focus bounds="14 1 2 2"/>
+  </circle>
+
+  <listener on="focus" target="a" emit="a-focus"/>
+  <listener on="blur" target="a" emit="a-blur"/>
+  <listener on="focus" target="b" emit="b-focus"/>
+  <listener on="blur" target="b" emit="b-blur"/>
+  <listener on="focus" target="c" emit="c-focus"/>
+  <listener on="blur" target="c" emit="c-blur"/>
+  <listener on="focus" target="outside" emit="outside-focus"/>
+  <listener on="blur" target="outside" emit="outside-blur"/>
+</anima>

package/modules/focus/capabilities/input-listen-focus/example.ani

@@ -0,0 +1,116 @@
+{
+  "anima": "0.1",
+  "name": "input-listen-focus",
+  "grid": 20,
+  "requires": ["focus"],
+  "inputs": {
+    "enabled": {
+      "type": "bool",
+      "default": true
+    }
+  },
+  "nodes": [
+    {
+      "id": "scope",
+      "type": "group",
+      "children": [
+        {
+          "id": "a",
+          "type": "circle",
+          "center": [2, 2],
+          "r": 1,
+          "fill": {
+            "color": "#000"
+          },
+          "focus": {
+            "bounds": [1, 1, 2, 2]
+          }
+        },
+        {
+          "id": "b",
+          "type": "circle",
+          "center": [8, 2],
+          "r": 1,
+          "fill": {
+            "color": "#000"
+          },
+          "focus": {
+            "enabledInput": "enabled",
+            "bounds": [7, 1, 2, 2]
+          }
+        },
+        {
+          "id": "c",
+          "type": "circle",
+          "center": [2, 8],
+          "r": 1,
+          "fill": {
+            "color": "#000"
+          },
+          "focus": {
+            "bounds": [1, 7, 2, 2]
+          }
+        }
+      ],
+      "focus": {
+        "enabled": false,
+        "scope": true,
+        "edge": "stop"
+      }
+    },
+    {
+      "id": "outside",
+      "type": "circle",
+      "center": [15, 2],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      },
+      "focus": {
+        "bounds": [14, 1, 2, 2]
+      }
+    }
+  ],
+  "listeners": [
+    {
+      "on": "focus",
+      "target": "a",
+      "emit": "a-focus"
+    },
+    {
+      "on": "blur",
+      "target": "a",
+      "emit": "a-blur"
+    },
+    {
+      "on": "focus",
+      "target": "b",
+      "emit": "b-focus"
+    },
+    {
+      "on": "blur",
+      "target": "b",
+      "emit": "b-blur"
+    },
+    {
+      "on": "focus",
+      "target": "c",
+      "emit": "c-focus"
+    },
+    {
+      "on": "blur",
+      "target": "c",
+      "emit": "c-blur"
+    },
+    {
+      "on": "focus",
+      "target": "outside",
+      "emit": "outside-focus"
+    },
+    {
+      "on": "blur",
+      "target": "outside",
+      "emit": "outside-blur"
+    }
+  ]
+}

package/modules/focus/capabilities/input-listen-focus/example.animl

@@ -0,0 +1,28 @@
+<anima version="0.1" name="input-listen-focus" grid="20" requires="focus">
+  <bool name="enabled" default="true"/>
+
+  <group id="scope">
+    <focus enabled="false" scope="true" edge="stop"/>
+    <circle id="a" cx="2" cy="2" r="1" fill="#000">
+      <focus bounds="1 1 2 2"/>
+    </circle>
+    <circle id="b" cx="8" cy="2" r="1" fill="#000">
+      <focus enabled-input="enabled" bounds="7 1 2 2"/>
+    </circle>
+    <circle id="c" cx="2" cy="8" r="1" fill="#000">
+      <focus bounds="1 7 2 2"/>
+    </circle>
+  </group>
+  <circle id="outside" cx="15" cy="2" r="1" fill="#000">
+    <focus bounds="14 1 2 2"/>
+  </circle>
+
+  <listener on="focus" target="a" emit="a-focus"/>
+  <listener on="blur" target="a" emit="a-blur"/>
+  <listener on="focus" target="b" emit="b-focus"/>
+  <listener on="blur" target="b" emit="b-blur"/>
+  <listener on="focus" target="c" emit="c-focus"/>
+  <listener on="blur" target="c" emit="c-blur"/>
+  <listener on="focus" target="outside" emit="outside-focus"/>
+  <listener on="blur" target="outside" emit="outside-blur"/>
+</anima>

package/modules/focus/examples/README.md

@@ -0,0 +1,10 @@
+# Focus traversal
+
+The row is a disabled focus target but an active closed-loop scope. Its two children
+opt into Tab traversal in order, with bounds for spatial arrow navigation. Pointer
+down also focuses a target. With input installed, keyboard delivery then calls the
+same focus navigation policy.
+
+Try `anima sample modules/focus/examples/traversal.animl -e "focus target first; key down ArrowRight; snapshot"`.
+In a web host load the focus and input entries; Tab enters the icon and traverses
+the two targets, Shift+Tab goes backward, and arrows move spatially.

package/modules/focus/examples/traversal.ani

@@ -0,0 +1,70 @@
+{
+  "anima": "0.1",
+  "name": "traversal",
+  "grid": 20,
+  "requires": ["focus", "input"],
+  "inputs": {
+    "second-focused": {
+      "type": "bool"
+    }
+  },
+  "nodes": [
+    {
+      "id": "row",
+      "type": "group",
+      "children": [
+        {
+          "id": "first",
+          "type": "circle",
+          "center": [5, 10],
+          "r": 3,
+          "fill": {
+            "color": "#4263eb"
+          },
+          "focus": {
+            "tabStops": true,
+            "order": 0,
+            "label": "First",
+            "bounds": [2, 7, 6, 6]
+          }
+        },
+        {
+          "id": "second",
+          "type": "circle",
+          "center": [15, 10],
+          "r": 3,
+          "fill": {
+            "color": "#4263eb"
+          },
+          "focus": {
+            "tabStops": true,
+            "order": 1,
+            "label": "Second",
+            "bounds": [12, 7, 6, 6]
+          }
+        }
+      ],
+      "focus": {
+        "enabled": false,
+        "scope": true,
+        "edge": "closed-loop"
+      }
+    }
+  ],
+  "listeners": [
+    {
+      "on": "focus",
+      "target": "first",
+      "set": {
+        "second-focused": false
+      }
+    },
+    {
+      "on": "focus",
+      "target": "second",
+      "set": {
+        "second-focused": true
+      }
+    }
+  ]
+}

package/modules/focus/examples/traversal.animl

@@ -0,0 +1,16 @@
+<anima version="0.1" name="traversal" grid="20" requires="focus input">
+  <bool name="second-focused"/>
+
+  <group id="row">
+    <focus enabled="false" scope="true" edge="closed-loop"/>
+    <circle id="first" cx="5" cy="10" r="3" fill="#4263eb">
+      <focus tab-stops="true" order="0" label="First" bounds="2 7 6 6"/>
+    </circle>
+    <circle id="second" cx="15" cy="10" r="3" fill="#4263eb">
+      <focus tab-stops="true" order="1" label="Second" bounds="12 7 6 6"/>
+    </circle>
+  </group>
+
+  <listener on="focus" target="first" set="second-focused=false"/>
+  <listener on="focus" target="second" set="second-focused=true"/>
+</anima>

package/modules/focus/manifest.source

@@ -0,0 +1,48 @@
+// Focus has no runtime dependency on other optional modules.
+export const after = ['components'];
+export default {
+  ...{
+    name: 'focus',
+    summary:
+      'Keyboard focus: focusable nodes, focus order, focus states and focus-driven listeners.',
+    after: [],
+    core: { entry: 'core/index.ts', export: 'focus', svg: 'core/svg.ts', svgExport: 'focusSVG' },
+    web: [{ name: 'focus', budget: 3456 }],
+    adapters: {
+      'packages/core/src/modules/focus/index.ts': 'core/index.ts',
+      'packages/core/src/modules/focus/svg.ts': 'core/svg.ts',
+      'packages/markup/src/focus.ts': 'markup/index.ts',
+      'packages/web/src/focus.ts': 'web/index.ts',
+    },
+    exports: {
+      'core:./focus': 'packages/core/src/modules/focus/index.ts',
+      'markup:./focus': 'packages/markup/src/focus.ts',
+      'web:./focus': 'packages/web/src/focus.ts',
+    },
+    tests: [
+      'modules/focus/test/**/*.test.ts',
+      'packages/markup/test/corpus.test.ts',
+      'packages/markup/test/names.test.ts',
+    ],
+    conformance: [
+      'input-focus-clear',
+      'input-focus-down',
+      'input-focus-edge-closed-loop',
+      'input-focus-edge-parent-scope',
+      'input-focus-edge-stop',
+      'input-focus-enabled',
+      'input-focus-left',
+      'input-focus-next',
+      'input-focus-previous',
+      'input-focus-pointer',
+      'input-focus-right',
+      'input-focus-target',
+      'input-focus-traverse',
+      'input-focus-up',
+      'input-listen-blur',
+      'input-listen-focus',
+    ],
+    docs: ['spec/SPEC.md', 'spec/ANIML.md', 'docs/WEB.md'],
+  },
+  after,
+};

package/modules/fonts/SPEC.md

@@ -0,0 +1,92 @@
+# Authored font options (normative, P6-13)
+
+Text styles accept `axes` (four-character ASCII alphanumeric/space tags to finite numbers)
+and `features` (tags to nonnegative integers). Declare `fonts` and `text`. The settings
+are maps in JSON and JSON-valued AniML attributes, following MODULES §Generic AniML fields:
+
+```xml
+<anima version="0.1" name="axes-features" grid="20" requires="text fonts">
+  <text id="label" x="2" y="2">
+    <style id="body" font="Inter" size="2" axes='{"wght":650}' features='{"kern":0,"liga":1}'/>
+    <run style="body" text="AB"/>
+  </text>
+</anima>
+```
+
+The fields work on local `<style>` and shared `<text-style>`. A local authored axis is
+bindable/animatable at `label.styles.body.axes.wght` using the existing numeric timeline,
+input-expression and data-bind rules. The axis must exist in the authored map. Features
+are static; selecting another run style can switch the feature map. Explicit `wght` axes
+win over style weight. Values outside the font's axis range clamp to its fvar endpoints.
+
+Import `@anima-format/web/fonts-options` for browser option support (includes fonts-text
+and text); import assets as usual for embedded fonts. Decoded byte/URL faces default to a `1 1000` weight descriptor, so a variable face's
+`wght` is selectable through Canvas; an explicit descriptor overrides that range.
+The resources-only fonts entry stays
+independent of the text renderer. The optional adapter preserves layout invalidation and
+readiness when a bound/animated axis changes. Per-glyph axes remain drawing effects and do
+not reflow the underlying line; style axes participate in measurement and line layout.
+
+SVG receives both `font-variation-settings` and `font-feature-settings`, including for
+per-glyph effects. Canvas uses `wght` as its numeric CSS font weight and `kern` as
+`fontKerning`. The weight fallback clamps to CSS’s 1–1000 range; fonts whose
+weight axis exceeds that range require the native arbitrary-axis API or SVG. It feature-detects native `fontVariationSettings` / `fontFeatureSettings`.
+On hosts without those APIs, other axes and arbitrary features are ignored by Canvas and
+Canvas measurement. SVG still applies the full settings, but runtime line breaking/carets
+use those fallback Canvas metrics and may differ from the drawn extents. The tool reader
+measures its supported options; `anima render --browser-text` shapes the resulting SVG. No synthetic
+property on an unsupported context is mistaken for platform support. These limitations
+are a browser capability boundary, not a promise of a full shaping engine (see
+`docs/research/rive-web-runtime.md` §1).
+
+The tool reader uses fvar/avar/gvar interpolation, including phantom-point advances;
+HVAR and unsupported variation formats retain `font-unsupported`. Unknown font axis tags
+produce `font-axis`; nonfinite axes and invalid feature values are errors. Absent feature
+tags produce a `font-feature` warning and have no effect. Four-character syntax and numeric
+ranges are also enforced by the authoring registry. The deterministic tool supports kern
+and context-free GSUB single, alternate and ligature substitutions (including extension
+lookups). It applies lookup order from the font; complex flags/contextual lookups fail
+with `font-unsupported` and a browser-rendering repair. Default ccmp/locl/rlig/liga/clig
+features are enabled, other substitutions require an explicit feature value. Script/language
+selection and complex-script shaping are not implemented; use the browser path. A ligature's
+advance is assigned to its first grapheme; the tool does not invent internal caret metrics.
+The implementation follows the primary [OpenType GSUB specification](https://learn.microsoft.com/en-us/typography/opentype/spec/gsub),
+not another runtime's source. No Rive implementation algorithm is used.
+
+### P7 variation platform boundary
+
+Arbitrary Canvas font axes remain conditional on a real `fontVariationSettings` member on the
+2D context. Both measurement and drawing use the same feature detection; unsupported hosts
+apply only `wght` via CSS font weight and `kern` via `fontKerning`. No invented property is
+assigned. SVG and tool outlines retain all supported authored axes. Both tested engines lack
+this Canvas API; the arbitrary-axis Canvas comparison is an evidenced platform skip, while
+wght retains its completed native raster comparison. Browser tests expose the detected support
+flags; synthetic-context tests exercise the native branch and reset settings between fonts.
+This limitation does not imply that unsupported axes render in Canvas or that fallback metrics
+match arbitrary-axis SVG drawing. The optional P7-8 fonts-info API below supplies explicit-byte decoding/metrics introspection.
+
+### Font introspection (P7-8)
+
+The optional [fonts-info contract](INFO.md) specifies decoded metrics, coverage, effective options,
+derived fonts and glyph paths in the browser and headless APIs. The resources-only entry still
+loads browser fonts without including this parser. Introspection explicitly requires SFNT source
+bytes; it cannot recover bytes from externally created FontFace objects.
+
+For example, after importing `@anima-format/web/fonts-info`:
+
+```ts
+const face = await icon.fonts.decode(sfntBytes);
+const font = await icon.fonts.info(face);
+font.metrics; // unitsPerEm, ascent, positive descent, lineGap, capHeight, xHeight, glyphCount
+font.hasGlyph(0x1f600); // cmap coverage, independent of CSS fallback
+const bold = font.derive({ axes: { wght: 900 } });
+bold.options; // immutable effective axes and supported feature settings
+bold.glyphs('AB'); // context-free glyphs, UTF-16 offsets, font-unit advance/path
+bold.glyphPath(34); // raw glyph index, baseline zero, +Y down
+```
+
+Headless clients import `decodeFont` from `@anima-format/core/fonts-info`. Tool clients with an
+already decoded CLI `Font` can use `new FontInfo(face)`. `font-source`, `font-format`,
+`font-invalid`, `font-axis`, `font-feature` and `font-unsupported` carry the API root pointer and a
+repair hint. Read INFO.md for the explicit SFNT/source-byte and shaping limits before choosing
+this API for a font with contextual scripts or variable metric tables.