@neocompose/cli 0.30.2 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.30.2",
+  "version": "0.31.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.30.2 -->
+<!-- reviewed-through-cli: 0.31.0 -->
 
 # Neo Compose CLI
 
@@ -109,6 +109,7 @@ neo/
   LocalizationStatuses/
   Files/{Images.neo,AudioClips.neo,Images/,AudioClips/}
   DialogueGroups/
+  Variants/{<Class>.neo,<Class>/<Folder path>.neo}
   Dialogues/*.neoflow
   Migrations/*.neo
   **/*.spec.neo
@@ -133,8 +134,9 @@ completely before editing:
   root/static bindings, nested/list identities, same-push references, unique
   keys, files, localization, and default materialization.
 - [Animation and world authoring](references/animation-and-world-authoring.md):
-  objects, sorting, optional children, structured leaves, partial animation
-  overrides, segments, tracks, and NeoFlow dialogues.
+  objects, sorting, optional children, structured leaves, object variants and
+  variant folders, partial animation overrides, segments, tracks, and NeoFlow
+  dialogues.
 - [NeoScript](references/neoscript.md): inline bodies, snippets, nullability,
   loops, switch, try/catch, ownership, evaluation, and migrations.
 - [Commands and synchronization](references/commands-and-sync.md): pull/push,

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

@@ -8,6 +8,7 @@ NeoFlow dialogue graphs.
 - World object contracts
 - Sorting and optional children
 - Structured leaves
+- Object variants
 - Animation overrides
 - Segments and tracks
 - NeoFlow dialogues
@@ -23,6 +24,67 @@ For world layer links, derive a concrete project class from
 `targetLayer` relation. Do not add value-level target metadata or ask painting
 operations to create/repair relation targets.
 
+## Object variants
+
+A variant is a named configuration of one `NeoObject`-derived class: how to
+construct a fresh instance, and how to move an existing one into the
+configuration. Variants are records parented to their class, never values
+inside it, so they live in their own `Variants/` family rather than in the
+class file.
+
+```neo
+// Variants/ExampleObject.neo
+@id("5f0c2b9e-7d41-4a58-9b1a-3f6f0e2d8c11")
+NeoVariant<ExampleObject> Down = new(
+  initialize: () => { return new ExampleObject(.Down); },
+  apply: (source) => { source.FacingDir = .Down; },
+);
+```
+
+- `initialize` takes no parameters and returns the target class. It is
+  required: it is the only way to construct through the variant.
+- `apply` takes exactly one parameter of the target class and is void. Omit it
+  for a variant that is only ever constructed.
+- Both are ordinary delegate closures: parenthesized parameter list, block
+  body, no expression-bodied form. The server compiles them, so authored source
+  carries only the code.
+
+Folders are records too, declared as their own globals and assigned per
+variant. Nesting is spelled in the path with `/`; intermediate segments are
+implicit, so `new("Trees/Oak")` needs no `Trees` record.
+
+```neo
+// Variants/ExampleObject/Inverted.neo
+@id("b7d2e9f0-3c15-4a68-8b24-9e0f1a2c3d44")
+NeoVariantFolder<ExampleObject> Inverted = new("Inverted");
+
+@id("e3b9c0d1-4a26-4f81-92e7-6b5a4c3d2e66")
+@settings(folder: Inverted)
+NeoVariant<ExampleObject> Down = new(
+  initialize: () => { return new ExampleObject(.Down); },
+);
+```
+
+Rules push enforces, and the language service reports live:
+
+- A variant or folder belongs to the class its single type argument names, and
+  a variant may only reference a folder of its own class.
+- Variant names and folder path segments share one generated static scope per
+  folder, and are unique within it case-insensitively. Two classes may each
+  declare a `Down`.
+- `Base` is reserved case-insensitively: `<Class>.Variants.Base` denotes the
+  class with no variant applied.
+- Every name must survive C# identifier normalization, since each becomes a
+  member of the generated `Variants` tree.
+
+Push is folder-agnostic as it is for every other record family: a variant
+declared in any `.neo` file anywhere pushes identically. `Variants/<Class>.neo`
+and `Variants/<Class>/<Folder path>.neo` are the canonical layout `neo pull`
+materializes, one file per (class, folder), folder record first and variants
+ordered by name. `NeoVariant` and `NeoVariantFolder` are reference-only: they
+declare variants as top-level globals and are never a member, entry, lookup
+target, parameter, or generic-binding type.
+
 ## Sorting and optional children
 
 Attach `NeoSortingGroup` as an optional nested member on the project object

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

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