@neocompose/cli 0.84.5 → 0.86.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.84.5",
+  "version": "0.86.0",
   "description": "Neo Compose native project-source CLI with bidirectional sync.",
   "license": "MIT",
   "type": "module",

package/skills/neocompose-cli/SKILL.md

@@ -9,7 +9,7 @@ description: >-
   `@neocompose/cli` or `node cli/bin/neo.mjs` in the neo-compose repository.
 ---
 
-<!-- reviewed-through-cli: 0.84.5 -->
+<!-- reviewed-through-cli: 0.86.0 -->
 
 # Neo Compose CLI
 

package/skills/neocompose-cli/references/cli-development.md

@@ -129,7 +129,7 @@ wrappers.
 The marker near the top of `SKILL.md` must exactly match the package version:
 
 ```html
-<!-- reviewed-through-cli: 0.84.5 -->
+<!-- reviewed-through-cli: 0.86.0 -->
 ```
 
 The quoted version above is checked too, so this instruction cannot go stale

package/skills/neocompose-cli/references/declarations-and-construction.md

@@ -61,6 +61,13 @@ it may extend another class but cannot be extended, cannot also be abstract,
 and can only be sealed while it has no subclasses. Interfaces can declare type
 parameters and pass arguments to the interfaces they extend; see Interface
 members.
+A `closed` class is implicitly abstract and defines an exhaustive subtype
+family within the project version. Do not combine `closed` with `abstract` or
+`sealed`. Descendants remain open unless explicitly sealed or closed. Every
+generic parameter of a direct subclass must appear in its base construction.
+Changing the family requires recompilation of its switch-expression consumers.
+Generated Unity C# uses an abstract class; C# 15 is not required.
+
 A read-only override may narrow a class or interface contract to an assignable
 class or derived interface, including a non-null value for a nullable contract.
 Generated Unity C# keeps the inherited property type for Mono compatibility;

package/skills/neocompose-cli/references/neoscript.md

@@ -148,16 +148,17 @@ Functions, natives and interface functions can declare their own type
 parameters after the name, each with an optional constraint and default:
 
 ```neo
-public static T? FirstOf<T extends Item = Item>(List<Item> items) {
-    foreach (Item item in items) {
-        if (item is T match) return match;
-    }
-    return null;
-}
+public static T? FirstOf<T extends Item = Item>(List<T> items) => items.FirstOrDefault();
 ```
 
 A call writes every type argument or omits the defaulted tail
-(`FirstOf<Seed>(items)`, `FirstOf(items)`); nothing is inferred. Function type
+(`FirstOf<Seed>(items)`, `FirstOf(items)`). When `<...>` is omitted, supplied
+arguments infer the function's type arguments. Lambda inputs bind first so their
+returns can infer output parameters, as in `Map(seed, (value) => value.Price)`.
+Defaults fill parameters with no inference evidence. The destination/expected
+return type does not provide evidence. Explicit `<...>` keeps explicit/default
+binding and does not infer omitted trailing arguments. Conflicting types require
+explicit arguments; inference does not invent a shared ancestor for siblings. Function type
 parameters take no `@id`, and an override declares the same count, constraints
 and defaults, though it may rename them.
 
@@ -384,12 +385,38 @@ Inside a generic body, `Reference<T>` takes the category of `T`'s binding.
 
 ## Numeric types
 
-`int` is a 32-bit integer and `float` is a 32-bit float, matching C#. Float
-literals, stored values, and every arithmetic step round to 32 bits, so
-`0.1f + 0.2f` behaves like Unity. `int` division truncates toward zero.
+`int` stores whole numbers and division truncates toward zero. Ordinary integer
+arithmetic retains the precision of the stored number. `float` literals, stored
+values, and every float arithmetic step round to 32 bits, matching Unity.
 `decimal` is exact base-10 and is the only type to use for currency or other
 values that must not drift.
 
+## Bitwise integer operators
+
+Use `~`, `&`, `^`, `|`, `<<`, `>>`, and `>>>` with non-nullable `int` operands.
+The compound forms are `&=`, `^=`, `|=`, `<<=`, `>>=`, and `>>>=`.
+Enums, bools, float literals such as `1.0`, and decimals are not accepted.
+Use `Set<Enum>` for enum membership.
+
+```neo
+int mask = (region << 8) | (tile & 255);
+bool hasEast = (mask & 2) != 0;
+mask &= ~2;
+```
+
+Each operand wraps modulo 2^32 into signed int32 at the bitwise boundary.
+Every result is signed int32. Ordinary integer arithmetic is unchanged.
+Shift counts use their low five bits: 32 means 0, 33 means 1, and -1 means 31.
+`>>` extends the sign bit; `>>>` fills with zero but still returns a signed
+result. Thus `-1 >>> 1` is 2147483647 and `-1 >>> 0` is -1.
+Operands evaluate once, left to right. A compound assignment captures its
+target and reads its old value before evaluating the right operand.
+
+Precedence from tightest to loosest: unary, switch expressions, multiplication/division/remainder,
+addition/subtraction, shifts, comparisons, equality and `is`, `&`, `^`, `|`,
+`&&`, `||`, `??`, then `?:`. Binary bitwise operators associate left to right.
+Keep shift characters contiguous: `x >> 1` is valid; `x > > 1` is not.
+
 ## Numeric builtins
 
 Use the `Math` namespace for numeric utilities with C# names and C# semantics:
@@ -413,6 +440,33 @@ enum, parameter, or local may shadow it. Qualified members use their owner's
 namespace and may be named `Math`; access one as `this.Math` or
 `SomeValue.Math` without colliding with the builtin qualifier.
 
+## Vector math
+
+`Vector2`, `Vector3`, `Vector2Int`, and `Vector3Int` support `+`, `-`, unary
+`-`, multiplication by a scalar in either order, and division by a scalar.
+Both vector operands must have the same type. Integer vectors accept only
+integer scalars; float vectors accept int or float. Integer division truncates
+toward zero. Division by zero throws. `==` and `!=` keep exact component equality.
+
+```neo
+Vector2 next = position + direction * speed;
+float distance = Vector2.Distance(position, target);
+Vector2 heading = (target - position).normalized;
+Vector2 step = Vector2.MoveTowards(position, target, speed);
+```
+
+All vectors expose read-only `magnitude` and `sqrMagnitude`, static `Distance`,
+`Min`, `Max`, and constants `zero`, `one`, `up`, `down`, `left`, and `right`.
+Three-dimensional vectors also have `forward` and `back`. Float vectors add
+`normalized`, `Dot`, `Lerp`, and `MoveTowards`; `Vector3` adds `Cross`.
+Integer vectors have no implicit conversion to float vectors.
+
+`Color.Lerp(a, b, t)` interpolates all four channels, including alpha.
+Both vector and Color `Lerp` clamp t to [0, 1]. `normalized` returns zero when
+the magnitude is at most 0.00001. A negative MoveTowards delta moves away.
+Computed properties are read-only; arithmetic, math results, and constants
+are fresh values. Component writes retain the ordinary vector aliasing rules.
+
 ## String builtins
 
 Use `text.Replace(search, replacement)` to return a string with every
@@ -424,6 +478,36 @@ may be null. The receiver stays unchanged.
 return "banana".Replace("a", "o"); // "bonono"
 ```
 
+Strings also have `Length`, `Substring(startIndex[, length])`, `IndexOf`,
+`LastIndexOf`, `Split(separator)`, `PadLeft`/`PadRight(totalWidth[,
+paddingChar])`, `Trim`, `TrimStart`, and `TrimEnd`, plus the statics
+`string.Join(separator, values)`, `string.IsNullOrEmpty`, and
+`string.IsNullOrWhiteSpace`. Lengths and indices count UTF-16 code units, every
+comparison is ordinal, and whitespace is C#'s `char.IsWhiteSpace` set. `Split`
+keeps empty entries and returns a new list. `Join` takes a `List<string>` or
+`Set<string>`; turn other entries into text first with
+`values.Select(v => $"{v}")`. `s?.Length` is an error; use
+`string.IsNullOrEmpty(s)` or narrow first.
+
+```neo
+List<string> parts = this.Text.Trim().Split(" ");
+int quantity = int.TryParse(parts[1]) ?? 0;
+return $"{slot.ToString("D3")} {price.ToString("N2")}";
+```
+
+`int.Parse`, `float.Parse`, and `decimal.Parse` accept ASCII digits with an
+optional sign (plus a fraction for `float` and `decimal`, and an exponent for
+`float`) after trimming ASCII whitespace, and throw on anything else or on a
+value the type can't hold. `TryParse` returns `null` instead of throwing.
+`decimal.Parse` never rounds: more than 28 significant or fractional digits is
+an error.
+
+Numbers format only with an explicit format: `D<n>` (int only, zero-padded),
+`F<n>` (fixed point), or `N<n>` (fixed point with `,` grouping), where `n` is 0
+to 28 and defaults to 2 (1 for `D`). `float` rounds half to even from its exact
+value, `decimal` rounds half away from zero, and a result that is all zeros has
+no `-` sign. For plain text, use interpolation: `$"{value}"`.
+
 Integer inputs assigned to `float` round to float32. This also applies to
 function arguments and returns, collection entries, and `List.Repeat` with a
 float entry type. `Contains` and `IndexOf` on float collections also convert
@@ -466,6 +550,44 @@ return this.Beds
   .Take(10);
 ```
 
+`Sum`, `Average`, `Min`, and `Max` accept zero arguments or one selector.
+Sum/Average require int, float, or decimal values; Min/Max also accept strings
+and bools. Null values are skipped. Sum returns zero on empty input; the other
+reductions return null for nullable input and throw for required input.
+Average of ints returns float. Decimal calculations stay exact; decimal Average
+rounds half-even within Neo's 28-digit envelope. Float Min stops at the first
+NaN; Max prefers ordinary values to NaN.
+
+`MinBy((item) => item.Score)` and `MaxBy(...)` return the first entry with the
+winning key. They skip null keys unless every key is null, then keep the first
+entry. Empty input throws unless the entry type is nullable.
+
+List and Set support `Aggregate((acc, item) => ...)`,
+`Aggregate(seed, (acc, item) => ...)`, `Distinct()`, and
+`Zip(other, (left, right) => ...)`. Aggregate visits entries in order; an empty
+unseeded fold throws. Distinct retains first occurrences using Contains equality
+and returns a read-only List, including nullable entries. Zip stops at the
+shorter input.
+
+`GroupBy((item) => item.Category)` returns a read-only dictionary of read-only
+lists. `ToDictionary((item) => item.Name)` optionally accepts a second value
+selector. Keys must be non-null strings or enum values; duplicate dictionary
+keys throw. Dictionary callbacks take `(key, value)`. `.Keys` and `.Values`
+return read-only lists in dictionary traversal order (integer-looking string
+keys precede other strings in numeric order).
+
+Chain `ThenBy` or `ThenByDescending` after OrderBy to add stable secondary keys.
+An inferred `var` retains this capability; ordinary List/Set annotations,
+function boundaries, and non-ordering queries erase it. Every ordering call is
+eager: it caches keys and sorts the snapshot, costing O(n log n * k) for k key
+levels. Each selector runs once per entry per level. Mutating a snapshot through an explicitly writable local alias invalidates its cached keys; ThenBy then throws until a new OrderBy establishes an ordering.
+
+Writable ordered lists support `items.Sort()` for scalar entries or
+`items.Sort((left, right) => left.Score - right.Score)` for an int comparison.
+Sort returns void, preserves entry identity, and is stable. It rejects mutation
+of the target list through aliases while comparisons run; entry fields retain
+their existing write permissions. A failed comparison leaves the order unchanged.
+
 Use `items.IndexOf(value)` to return the zero-based index of the first equal
 list entry, or `-1` when the value is absent. `IndexOf` is list-only and uses
 the same equality as `Contains`.
@@ -597,8 +719,39 @@ switch (direction) {
 Permit `int`, `string`, `bool`, enum, and nullable forms. Stack labels when
 they share one body. End every reachable non-empty section with `break`,
 `return`, `throw`, or `continue` when a surrounding loop makes it valid.
-Do not use implicit fallthrough, switch expressions, pattern cases, guards, or
-`goto`.
+Do not use implicit fallthrough, pattern cases, guards, or `goto` in statement switches.
+
+### Switch expressions
+
+Use `value switch { pattern => result, ... }` to produce one value. Arms may
+use scalar/enum constants, `null`, type patterns (`Damage`), declaration
+patterns (`Damage damage`), or `_`. A declaration binding is scoped to its
+arm's optional `when` guard and result. Patterns and guards run in order; the
+selector runs once and only the chosen result runs.
+
+```neo
+closed class HitResult {}
+sealed class Miss : HitResult {}
+sealed class Damage : HitResult { public int Amount = 0; }
+class Combat {
+  public string Describe(HitResult result) => result switch {
+    Miss => "miss",
+    Damage damage when damage.Amount > 10 => "strong hit",
+    Damage damage => $"{damage.Amount}",
+  };
+}
+```
+
+Every switch expression must be exhaustive. Handle every bool/enum option or
+closed-class branch, plus null for nullable input. Other types require a
+covering type or `_` fallback. A guard contributes no exhaustive coverage
+unless it is literally `true`. Missing and unreachable cases are compile
+errors. Adding a new subtype recompiles affected consumers.
+
+Result arms must fit the expected type or have a common assignable type.
+Property, relational, list, and positional patterns are unsupported. Pattern
+cases in statement switches remain unsupported. Install the matching Unity
+SDK before exporting the new switch-expression IR; older SDKs reject it.
 
 ## Try/catch