@neocompose/cli 0.75.1 → 0.76.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.75.1",
+  "version": "0.76.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.75.1 -->
+<!-- reviewed-through-cli: 0.76.0 -->
 
 # Neo Compose CLI
 
@@ -211,8 +211,12 @@ copies, use the editor's duplicate action or copy the initializer without IDs.
 Scalars may have several owners. If those values diverge in web, pull keeps
 the different server values by inlining the differing uses. Initializer
 aliases are local source organization, not runtime globals or server records.
-Use their names as complete value initializers; executable expressions such as
-`BASE + 1` cannot access these local declarations.
+Complete member and collection entries compose owned values, including inside
+constructor-backed initializers. A class local used as a constructor argument or
+executable operand refers to its single stored instance. Nested targets need an
+existing `@id` or an authored UUID-v4; a direct static owner supports pending IDs.
+Scalar executable expressions such as `BASE + 1` still require inlining the
+scalar expression. Locals are unavailable inside executable closures.
 The shared editor offers extract-to-file on a selected complete initializer,
 inline on its sole use, and duplicate at a use. Move the created file freely.
 
@@ -308,5 +312,6 @@ and `insert_final_newline` there to keep regenerated source consistent with your
 editor. Defaults are two spaces, LF, and a final newline. Push preserves authored
 text when regeneration has the same tokens; pull preserves semantically unchanged
 files. Formatting-only body or source-location changes do not create a subsequent
-push; real code and string-content edits still do. Formatting preferences belong
+push, including stored initializer recipes, computed member defaults, and inline
+constructor delegates; real code and string-content edits still do. Formatting preferences belong
 to the checkout, not stored script bodies.

package/skills/neocompose-cli/references/animation-and-world-authoring.md

@@ -66,8 +66,9 @@ new GlassFloorTile { Cell = new(9, -4) }
 
 Layer-link `Tiles` lists contain these values directly. `NeoTileInstance` and
 `@tile(...)` are removed. A tile's `Name`, `Sprite`, and `SmartTile` are
-`readonly` declaration members. Override them on a subclass; a placement
-initializer cannot assign them. `Cell` is the placement's writable field.
+class-level `readonly` members: tiles render per class, so override them on a
+subclass. Push rejects a placement that sets them. `Cell` is the placement's
+writable field.
 
 Object `PlacementTiles` is a `List<NeoPlacementTile>`. Each entry marks a
 footprint cell with its own `Cell` member. It is independent of `NeoTile`. Rendered

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

@@ -105,7 +105,10 @@ project-file bytes, and web editor commits use the shared client preparation pro
 Unrelated source files are not uploaded or recompiled on every push.
 Optional source maps missing from valid stored bodies do not request a backfill.
 Formatting-only source location changes do not create pushes, including when
-other records change. Evaluation maps the current local layout; authored edits,
+other records change. Stored initializer recipes, computed member defaults, and
+inline constructor delegates preserve their pulled code and compiled bodies when
+source tokens are unchanged. String-literal content remains significant.
+Evaluation maps the current local layout; authored edits,
 dependency changes, and explicit forced recompilation retain their normal compile scope. A CLI lowering mismatch on a normal push is exposed by the next
 canonical pull; `neo push --dry-run` remains the complete source-to-record
 rehearsal.
@@ -126,7 +129,7 @@ wrappers.
 The marker near the top of `SKILL.md` must exactly match the package version:
 
 ```html
-<!-- reviewed-through-cli: 0.75.1 -->
+<!-- reviewed-through-cli: 0.76.0 -->
 ```
 
 The quoted version above is checked too, so this instruction cannot go stale

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

@@ -166,6 +166,24 @@ a User class reads only `root.User`. Other code reads `root.User` but can't
 assign, mutate, construct, or invoke User data. Lookups and listeners don't
 cross between User and Save data; Session lookups may target `root.User`.
 
+`readonly` is init-only, as in C#, and independent of storage. A field
+initializer, a constructor body, an object initializer block, or an authored
+value sets it; nothing writes it after construction. It is valid on Save,
+Session, Immutable, and User classes, but not with Writable storage. It may
+read a header parameter:
+
+```neo
+class MixerGroup(string name) {
+  public readonly string Name = name;
+  public readonly List<MixerChannel> Children = [];
+  public float Volume = 1;
+}
+```
+
+Readonly is shallow. A readonly collection's membership is fixed, while its
+entries' members follow their own storage and mutability. User class members
+still declare no storage.
+
 `@index(member: Field, kind: .Unique)` and
 `@column(member: Field, width: ..., visibility: ..., pin: ..., overflow: ...)`
 are repeatable List annotations. `member:` is a bare field name on the entry
@@ -369,8 +387,8 @@ Accept settlement only from:
 
 1. The member's own initializer expression.
 2. Assignment on every reachable path in `init` or a constructor body.
-3. A call-site initializer entry when using an otherwise valid construction
-   path.
+3. A call-site initializer entry, in value source and NeoScript bodies alike,
+   when using an otherwise valid construction path.
 
 Do not infer settlement from a side effect inside another function. Require
 full `if`/`else` coverage when an assignment is conditional.
@@ -434,7 +452,21 @@ class PlacedItem<
 }
 ```
 
-Executable object initializer blocks can set immutable stored members on the newly constructed instance, including nested `new` expressions. Ordinary assignments after construction remain subject to storage restrictions. `readonly` declarations still change only through class defaults.
+Object initializer blocks can set `readonly` members of the newly constructed
+instance, including nested `new` expressions. Ordinary assignments after
+construction remain subject to storage and `readonly` restrictions.
+
+Runtime construction never supplies an Immutable member: an initializer block,
+constructor body, base-clause argument, or generated C# factory cannot set one.
+The value is never stored with the instance. When the declaration, including
+every row it owns, reads neither `this` nor a constructor argument, the member
+is a constant and every instance shares one value. Otherwise each instance
+evaluates the declared initializer with its own `this` and constructor
+arguments, again after a reload. A method group such as `selector: SelectTorso`
+binds `this`. `Clone()` shares an authored or constant Immutable value and
+re-evaluates a per-instance one. A class with a required Immutable member and
+no initializer cannot be constructed at runtime; only authored values construct
+it.
 
 Populated unordered member defaults, such as `@settings(kind: .Unordered)` with
 `List<Entry> Entries = [new Entry()]`, are constructed by an initializer for
@@ -446,3 +478,28 @@ A lookup's declared class must be assignable to the entry class of its
 selection. Constructor arguments and member initializers must select compatible
 targets too. An `NPC` lookup cannot select from `List<Quest>`, even when its
 initializer is typed `NPC`; status reports the conflicting collection annotation.
+
+Schema export retains a constructed default's generic arguments, including
+nested collection references. For example, a `NeoAnimationClip<ArmPart>`
+default constructs `new NeoAnimationClip<ArmPart>` and its frames reference
+`List<NeoAnimationFrame<ArmPart>>`.
+
+When a construction leaves a required member unsettled, CLI diagnostics point to
+`new` and include the member declaration as a related location. Fix that
+construction before pushing. Valid root initializers still participate in
+reference checking, so an unrelated root error does not imply their values are
+missing or deleted. Independent reference errors remain visible.
+
+Object initializer assignments use commas. The last comma is optional; the
+semicolon terminating the enclosing declaration is valid:
+
+```neo
+AudioSettings AUDIO_SETTINGS = new() {
+  Main = new AudioMixerGroupSettingsFolder("Main", "Master", "MasterVolume", []),
+};
+```
+
+A semicolon after `Main = ...` inside the initializer is invalid. Editor and CLI
+diagnostics highlight that separator in the authored file, including global,
+static member, and protected root initializers. Statement semicolons inside
+function or delegate bodies remain valid.

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

@@ -154,9 +154,10 @@ Object initializers are available in method bodies and `.spec.neo` tests:
 var tile = new DirtWetTile { Cell = Vector2Int(3, -2) };
 ```
 
-Construction runs first. Each initializer entry then uses ordinary assignment
-rules in source order, including property setters, access checks, and readonly
-restrictions. Initializer expressions read the caller's scope.
+An entry that settles a required member is evaluated with construction, as the
+constructor argument it stands in for. The remaining entries then use ordinary
+assignment rules in source order, including property setters, access checks,
+and readonly restrictions. Initializer expressions read the caller's scope.
 
 ## Nullability and ownership
 

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

@@ -90,6 +90,45 @@ formatting moves its ID above the declaration. Do not put an ID in both places.
 A local initializer such as `Delivery DeliveryRow = new()` retains `Delivery`
 when consumed by a base-class member. Aliases retain that same concrete type.
 
+Complete local member and collection initializers also work inside constructions
+that execute a constructor. Each local composes its owned subtree and preserves
+its concrete class:
+
+```neo
+AudioFolder SFX_FOLDER = new("Sound effects") {
+  Children = [UI_VOLUME, GAMEPLAY_VOLUME]
+};
+AudioSettings AUDIO_SETTINGS = new() { Main = SFX_FOLDER };
+```
+
+In constructor arguments and executable operands, a class local names its one
+stored instance instead of constructing a copy:
+
+```neo
+@id("86ac7c7d-8d3b-4642-9def-cdf32643bdc5")
+DeliveryQuest HARD_AS_STONE = new();
+// The core quest list owns HARD_AS_STONE.
+WorkflowStep UNLOCK = new QuestUnlockStep(HARD_AS_STONE);
+```
+
+The referenced local must have exactly one owning placement. A nested target
+needs its existing `@id`. A structurally owned list entry can also use an unused
+UUID-v4 in the same push. For a local nested inside an evaluated constructor,
+leave it idless on the first push; push assigns its actual identity before it can
+be referenced. Do not assign a fresh UUID to that nested construction. A direct static owning member can supply an idless local's pending identity.
+Aliases of that static local work too. A member default is a construction template,
+so its local does not identify a single stored instance. Unowned locals, ambiguous
+placements, and cycles are errors at source. Constructor argument type checking
+still applies. Canonical construction arguments may use `Reference<Type>(id: "…")`.
+
+Owned locals inside evaluated initializers need directly addressable fields, list
+entries, or literal dictionary keys; inline the construction when a computed key
+or other executable expression prevents tracking its owning path.
+
+Scalar locals remain complete-initializer bindings; inline their expressions when
+using them in arithmetic or constructor arguments. Closure bodies cannot capture
+project authoring locals.
+
 Nested class/list rows remain independently addressable and keep inline IDs:
 
 ```neo