@neocompose/cli 0.84.4 → 0.85.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.84.4",
+  "version": "0.85.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.4 -->
+<!-- reviewed-through-cli: 0.85.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.4 -->
+<!-- reviewed-through-cli: 0.85.0 -->
 ```
 
 The quoted version above is checked too, so this instruction cannot go stale

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

@@ -124,6 +124,26 @@ class members and `IReceiver` members. The same applies to guards that return,
 throw, or break. Reassignment clears the proof, and paths that did not pass the
 guard cannot use it.
 
+A class can construct each interface only once. A class value known to implement
+`IBox<int>` cannot pass an `is IBox<string>` check, including through inherited
+interfaces. Open classes can still acquire an unrelated interface. Checks between
+interface-only receivers retain their runtime behavior.
+
+Guards preserve a generic receiver's `T` identity and its declared bound. A
+declaration pattern also keeps the original receiver's members: after
+`if (item is not IReceiver receiver) return;`, `item` still has its class or
+generic type, while `receiver` exposes `IReceiver`.
+
+A later class guard retains these capabilities. For example, after checking
+`item is IReceiver` and then `item is Furnace`, the original `item` exposes both
+`Furnace` and `IReceiver` members. A sealed class that cannot implement the
+proven interface remains an impossible test.
+
+Guards also narrow named global values and static member paths. Qualified and
+unqualified static access share the same proof, including inherited statics.
+Assignments clear affected proofs. A closure must establish its own guard
+because the stored value can change before the closure runs.
+
 Functions, natives and interface functions can declare their own type
 parameters after the name, each with an optional constraint and default:
 
@@ -172,18 +192,19 @@ Each instance binds defaults that read `this` to itself; invalid lambda bodies
 are reported at the declaration by status, editor validation, and preparation.
 Static delegate fields use static class scope: they can read static members
 without an instance owner, and cannot access `this` or instance members.
-Other static fields can call them in their initializers, as in
-`public static int First = Helper.Run();`. Outside a lambda body, a field
-initializer qualifies the members it reads; a bare `Run()` or `Number` there is
-an unknown name.
-A delegate field default is the exception: it may name a method group bare.
+Field initializers can read their declaring class's static members without a
+qualifier, including inherited statics and reads inside nested object defaults:
+`public int First = Run();` and `public static int Copy = Number;`.
+Eager initializers cannot read instance members or `this`; static defaults also
+cannot capture class-header parameters. Defer instance reads inside a delegate
+lambda. A delegate field default may also name a method group bare.
 `Value = Read` or `this.Read` binds each new instance to its own `Read`, and a
 static function may be named as `Read` or qualified as `Holder.Read`/`Other.Read`.
 A qualified method group must name a static function. Method groups use the same
 signature rule as in a body, and a mismatch is reported at the declaration.
 A static field that names another static copies a value, as in
 `public static int B = Holder.A;`. A class, List, Set, or Dictionary static
-already owns its value, so call `Clone()` or use `Reference`. A static delegate cannot copy another Class's delegate field,
+already owns its value, so call `Clone()` or use `Reference`. A static delegate cannot copy another Class's delegate field, including an inherited one,
 because its closure compiles in its own Class; wrap it as `() => Other.Call()`.
 Omitted constructor fields use their authored defaults, including optional fields.
 Writable collection defaults belong to each instance; mutations persist on later
@@ -195,7 +216,13 @@ needed type descriptors; spec-only types remain in the test candidate.
 Generic primary constructors also accept stored collection arguments, such as
 `public static Box<List<int>> Value = new([1, 2]);`. Stored replay uses the closed
 parameter type to preserve collection references.
+Stored constructors validate every authored type argument, including names nested
+inside collections and generic types. An expected field type cannot hide an unknown
+type in `new Box<List<MissingType>>()`.
 Typed locals also accept generic class types such as `Box<int> box = new(1);`.
+Generic class arguments remain invariant through inheritance: `IntBox : Box<int>`
+can be assigned to `Box<int>`, but not `Box<string>`. Arguments are substituted
+through every intermediate base class, including nested generic arguments.
 Explicit lambda parameter annotations accept the same type grammar as
 declarations, including `decimal`, generic parameters, collections, arrays, and
 nullable types.
@@ -266,6 +293,9 @@ conditions being false also narrow receivers in later `else if` conditions.
 A nullable value coalesced with a non-null fallback produces a non-null result,
 including in constructor arguments: `new Sprite(item.Sprite ?? SpriteInfo.Empty)`.
 A nullable fallback keeps the result nullable when the left operand can be null.
+When a reference result is expected, `first ?? fallback` selects the reference
+itself. A present reference to a null target does not select the fallback.
+In a scalar context, references still read their targets before coalescing.
 
 Treat lookup-return values with the same nullable narrowing rules.
 
@@ -332,6 +362,12 @@ this.A = Reference(this.Count);   // A now names Count
 this.A += 1;                      // reads A's target, writes it back
 ```
 
+Conditional assignments such as `this.A = choose ? first : second` rebind `A`
+when both branches supply references. Scalar branches write through `A`; a mixed
+reference and scalar choice reads the selected reference's target. Constructors
+may initialize their own reference fields this way, but cannot write through
+external targets.
+
 A plain value never becomes a reference: passing `3` to a `Reference<int>`
 parameter is an error. A handle reference never owns, so it can't hold a new
 list or a query result.
@@ -377,6 +413,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
@@ -388,6 +451,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
@@ -430,6 +523,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`.

package/skills/neocompose-cli/references/values-identities-and-references.md

@@ -239,6 +239,10 @@ Reference<NeoDialogue>(id: "capitol-dialogue-id")
 - Both forms are legal in a member's declaration default, not only inside a
   value graph. A key written there resolves after every pass has run, so it may
   name a row the same push creates.
+- List and dictionary declaration defaults can contain slot references, including
+  nested collections: `List<Reference<int>> Counts = [Reference(root.Save.Bits)]`.
+  Each instance owns its collection; entries continue to target the original
+  root or static slot, including slots supplied by declaration defaults.
 - Keep genuine structural references ID-based when their collection has no
   stable symbol, path, or key surface. Animation track and frame-override
   targets are selectors, not structural references: encode a stable