@neocompose/cli 0.89.0 → 0.89.2

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

@@ -26,7 +26,8 @@ public Reference<int> TrackedStat;          // another member's int
 
 - `Reference<T>` also works as a parameter, collection element, dictionary
   value, and unbound generic argument (`Box<Reference<int>>`), and keeps that
-  storage type through push and pull. Use `Set<T>` parameters for several
+  storage type through push and pull, including nested generic collections
+  and named tuples. Use `Set<T>` parameters for several
   selections.
 - `@settings(collection: Owner.Member)` binds a class reference to one
   collection. Unbound references select any stored row of `T` or a subclass,
@@ -47,20 +48,38 @@ public Reference<int> TrackedStat;          // another member's int
 
 ```neo
 public Reference<Item> StarterSeed = root.Assets.Items.Index.Slug["seed.carrot"]!;
-public Reference<int> Gold = Reference(root.Player.Gold);
-public Reference<string> Greeting = Reference(root.Npcs.Index.Slug["mira"]!.Greeting);
-public Reference<NeoVariant<Tree>> Look = Reference(root.Garden.Felled);
+public Reference<int> Gold = root.Player.Gold;
+public Reference<string> Greeting = root.Npcs.Index.Slug["mira"]!.Greeting;
+public Reference<NeoVariant<Tree>> Look = root.Garden.Felled;
 ```
 
 - An unbound handle default may name its row by a unique index: a `root`
   path to a List, `.Index.<Name>`, and a string literal key. Other shapes are
   initializer code.
-- Slot defaults wrap a member path in `Reference()`. A plain value is not a
-  default, and `this` doesn't exist yet. A `NeoVariant<T>` member's own
-  default stays the bare variant path.
+- Slot defaults accept compatible stored member paths directly; `Reference()`
+  remains valid. Literals and computed values cannot supply a slot, and `this`
+  does not exist yet. A `NeoVariant<T>` member's own default stays the bare
+  variant path.
 - List and dictionary defaults may hold slot references, nested too:
-  `List<Reference<int>> Counts = [Reference(root.Save.Bits)]`. Each instance
+  `List<Reference<int>> Counts = [root.Save.Bits]`. Each instance
   owns the collection; entries target the original slots.
+- `Set<Reference<T>>` selections can mix bare paths and explicit references.
+  Computed selections deduplicate by target identity, not by current value.
+  A literal selection of fixed targets must not repeat the same target.
+  A selection literal may also evaluate its entries, for example
+  `[root.Assets.Items.First(), selected]`. Those entries must resolve to
+  existing objects; the selection evaluates when its owner is constructed.
+  A compatible `Set<T>` path is a computed selection, including a set of a
+  derived class assigned to `Set<Reference<Base>>`. Each selected object keeps
+  its identity; the selection does not acquire the source collection's row.
+  Convert a `List<T>` to a set with `.ToSet()`.
+- A bare path to an existing reference copies its current target when the
+  object is constructed. Later rebinding of that source reference does not
+  rebind the copy.
+- A nullable target still needs a stored row. Pin an otherwise absent
+  nullable member in its owner's initializer, for example
+  `new() { Maybe = null }`, before referencing it. A declaration default alone
+  does not create that row.
 
 ## Source forms
 
@@ -89,11 +108,18 @@ Reference<NeoDialogue>(id: "capitol-dialogue-id")
 
 ## Runtime semantics
 
-`Reference(place)` forms a reference to a stored member: `this.Gold`,
-`root.Player.Gold`, `item.Count`. Locals, parameters, list or dictionary
-elements, vector components, getters, query results, and new values have no
-row. When `Selected` is `Reference<Item>`, `Reference(this.Selected)` is
-`Reference<Reference<Item>>`. Access checks apply where it is formed.
+When executable code expects `Reference<T>`, pass a compatible stored member
+such as `this.Gold`, `root.Player.Gold`, or `item.Count` directly. This works
+for constructor and function arguments, returns, typed locals, object
+initializers, and collection entries. The reference keeps following that
+slot when its value changes. `Reference(place)` remains valid when an
+explicit reference is needed.
+
+Locals, parameters, list or dictionary elements, vector components, getters,
+query results, and new scalar values have no row. A narrowed nullable member
+still names its declared storage type. When `Selected` is `Reference<Item>`,
+`Reference(this.Selected)` is `Reference<Reference<Item>>`. Access checks
+apply where the reference is formed.
 
 ```neo
 this.A = 5;                       // writes 5 into A's target
@@ -106,8 +132,8 @@ this.A += 1;                      // reads A's target, writes it back
 - Assigning a same-typed reference rebinds; anything else writes through.
   `this.A = c ? first : second` rebinds when both arms are references, writes
   when both are scalars, and reads the chosen target when mixed.
-- A plain value never becomes a reference: passing `3` to a `Reference<int>`
-  parameter is an error.
+- A value without a stored slot never becomes a reference: passing `3` to a
+  `Reference<int>` parameter is an error.
 - Constructors may initialize their own reference fields but can't write
   through external targets.
 - `==` compares handles by identity and slots by value. Collections of
@@ -138,6 +164,10 @@ Lookup assignment still needs an existing backing row.
 (`root.Assets.Quests.Daily` or `Reference(root.Assets.Quests.Daily)`) and
 follow the same rules. The path may cross construction defaults and
 declarations from the same push; no preliminary push or manual ID is needed.
+Pull emits bare paths in `collectionValue` settings when the target is reachable
+from a root; otherwise it retains `Reference(id: "...")`. Lookup variant folder
+bindings and `.Bind(root.Assets.Items.Index.Slug["seed.carrot"]!)` use the same
+implicit reference conversion.
 Invalid reference settings are errors, never silently dropped.
 
 ## Init-built objects
@@ -145,7 +175,7 @@ Invalid reference settings are errors, never silently dropped.
 An object `Root.neo` writes is init-built when its class has an `init` block.
 A declaration binding may name a member inside it, and push stores that
 member's row. A reference captured by `init` or a constructor
-(`new Rule(Reference(this.Weather))`) keeps its target's row. Status refuses a
+(`new Rule(this.Weather)`) keeps its target's row. Status refuses a
 value row's reference to a member of an init-built object (bind it from a
 declaration instead) and a binding to a class or list that an `init` block
 builds.

package/skills/neocompose-cli/references/world/variants.md

@@ -86,7 +86,7 @@ class root.
 NeoLookupVariantFolder<ExampleObject, NeoSortingLayer> Root = new(
   path: "",
   collection: Assets.SortingLayers,
-  collectionValue: Reference(root.Assets.SortingLayers),
+  collectionValue: root.Assets.SortingLayers,
 );
 
 @id("736dddf8-2881-47e1-a1d3-55fb65ea9f2a")
@@ -97,13 +97,14 @@ NeoLookupVariant<ExampleObject, NeoSortingLayer> Layered = new(
 ```
 
 - `collection` names the eligible list member; `collectionValue` the stored
-  list whose rows it enumerates. Prefer the `Reference(root...)` form pull
+  list whose rows it enumerates. Prefer the bare `root...` path pull
   emits.
 - Lookup `initialize` receives the row; lookup `apply` receives the object,
   then the row.
 - A `NeoLookupVariant<TObject, TValue>` member holds an unbound handle. A
   plain `NeoVariant<TObject>` member may pick one row with
-  `.Bind(Reference(...))`; never bind a row to the lookup-handle type.
+  `.Bind(root.Assets.Items.Index.Slug["seed.carrot"]!)`; explicit
+  `Reference(...)` remains valid. Never bind a row to the lookup-handle type.
 
 ## Type restrictions