@neocompose/cli 0.21.2 → 0.21.4

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.21.4] - 2026-08-03
+
+### Fixed
+
+- `neo pull --reset` emits the canonical `SpriteInfo.Empty` spelling for the
+  required empty-sprite sentinel and does not mistake its empty file id for a
+  missing project file.
+- Parameterized declaration templates compile with their class-header scope
+  without being evaluated before a concrete invocation supplies arguments.
+- Canonical lowering reuses persisted generic argument identities, so a fresh
+  reset remains a semantic no-op instead of creating replacement binding rows.
+
+## [0.21.3] - 2026-08-03
+
+### Fixed
+
+- `neo push` paints its preparation spinner before workspace discovery,
+  lowering, and NeoScript compilation begin, so large projects no longer look
+  stalled before the push plan appears.
+- Animation segment frame values are emitted through the required `value`
+  constructor argument. Required sprites use the canonical `SpriteInfo.Empty`
+  value; `null` is reserved for nullable `SpriteInfo?` values.
+
 ## [0.21.2] - 2026-08-03
 
 ### Fixed

package/dist/neo.mjs

@@ -842,7 +842,7 @@ function vectorTypes() {
     members: structuredLeafFieldProperties(name)
   }));
 }
-var NEOSCRIPT_KEYWORDS, NEOSCRIPT_INFERRED_LOCAL_KEYWORD, NEOSCRIPT_CONSTRUCTOR_KEYWORD, NEOSCRIPT_PRIMITIVE_TYPES, NEOSCRIPT_BUILTIN_TYPES, NEOSCRIPT_OPERATORS, NEOSCRIPT_STATEMENT_SNIPPETS, STRING_TYPE, INT_TYPE, FLOAT_TYPE, BOOL_TYPE, IMAGE_REF_TYPE, FLOAT_OPTIONAL_TYPE, NEOSCRIPT_STRUCTURED_LEAF_FIELDS, NEOSCRIPT_IMAGE_REGISTRY_TYPE, NEOSCRIPT_AUDIO_CLIP_REGISTRY_TYPE, NEOSCRIPT_PENDING_SYMBOL_ID_PREFIX, REGISTRY_ENTRY_TYPES, NEOSCRIPT_GLOBALS, NEOSCRIPT_BUILTIN_TYPE_SYMBOLS;
+var NEOSCRIPT_KEYWORDS, NEOSCRIPT_INFERRED_LOCAL_KEYWORD, NEOSCRIPT_CONSTRUCTOR_KEYWORD, NEOSCRIPT_PRIMITIVE_TYPES, NEOSCRIPT_BUILTIN_TYPES, NEOSCRIPT_OPERATORS, NEOSCRIPT_STATEMENT_SNIPPETS, STRING_TYPE, INT_TYPE, FLOAT_TYPE, BOOL_TYPE, IMAGE_REF_TYPE, SPRITE_INFO_TYPE, FLOAT_OPTIONAL_TYPE, NEOSCRIPT_STRUCTURED_LEAF_FIELDS, NEOSCRIPT_IMAGE_REGISTRY_TYPE, NEOSCRIPT_AUDIO_CLIP_REGISTRY_TYPE, NEOSCRIPT_PENDING_SYMBOL_ID_PREFIX, REGISTRY_ENTRY_TYPES, NEOSCRIPT_GLOBALS, NEOSCRIPT_SPRITE_INFO_EMPTY_MEMBER_ID, NEOSCRIPT_SPRITE_INFO_EMPTY_VALUE, NEOSCRIPT_BUILTIN_TYPE_SYMBOLS;
 var init_language_spec = __esm({
   "../packages/neoscript-language/src/language-spec.ts"() {
     "use strict";
@@ -1006,6 +1006,10 @@ var init_language_spec = __esm({
       kind: "primitive",
       name: "ImageRef"
     };
+    SPRITE_INFO_TYPE = {
+      kind: "primitive",
+      name: "SpriteInfo"
+    };
     FLOAT_OPTIONAL_TYPE = {
       kind: "primitive",
       name: "float",
@@ -1148,12 +1152,26 @@ var init_language_spec = __esm({
         "Returns whether a dialogue pointer has been visited."
       )
     ];
+    NEOSCRIPT_SPRITE_INFO_EMPTY_MEMBER_ID = "builtin:SpriteInfo:property:Empty";
+    NEOSCRIPT_SPRITE_INFO_EMPTY_VALUE = Object.freeze({
+      fileId: "",
+      sliceIndex: 0
+    });
     NEOSCRIPT_BUILTIN_TYPE_SYMBOLS = [
       {
         id: "builtin:SpriteInfo",
         name: "SpriteInfo",
         kind: "builtin",
         members: [
+          {
+            ...property(
+              "SpriteInfo",
+              "Empty",
+              SPRITE_INFO_TYPE,
+              "An authored empty sprite at slice zero."
+            ),
+            static: true
+          },
           // `FileId` and `SliceIndex` come from the field table above — they are
           // the writable, addressable fields, not derived properties (D11).
           ...structuredLeafFieldProperties("SpriteInfo"),
@@ -9027,7 +9045,8 @@ var init_strict_resolver = __esm({
             );
           case "call":
             if (expression.callee.kind === "ident" && expression.callee.name === "Reference" && Array.isArray(expression.typeArguments)) {
-              if (expression.typeArguments.length !== 1) {
+              const [referenceTypeArgument] = expression.typeArguments;
+              if (expression.typeArguments.length !== 1 || referenceTypeArgument === void 0) {
                 throw new CompileError(
                   "Reference requires exactly one generic target type.",
                   expression.pos
@@ -9039,7 +9058,7 @@ var init_strict_resolver = __esm({
                   expression.pos
                 );
               }
-              const referencedType = this.resolveType(expression.typeArguments[0]);
+              const referencedType = this.resolveType(referenceTypeArgument);
               if (expected !== void 0 && !isNeoScriptTypeAssignable(referencedType, expected, this.project)) {
                 throw new CompileError(
                   `Reference target ${this.describe(referencedType)} is not assignable to ${this.describe(expected)}.`,
@@ -9093,7 +9112,7 @@ var init_strict_resolver = __esm({
             if (requiredConstructor === null && !callMatchesDeclaredOverloadNames(declared, expression)) {
               this.rejectConstructorProjectionInConstructionBody(expression);
             }
-            const projectionCall = requiredConstructor === null && expression.argumentNames === void 0 && callHasPositionalArguments(expression) && declaredTarget?.constructorSignature !== void 0;
+            const projectionCall = requiredConstructor === null && declaredTarget?.constructorSignature !== void 0 && (expression.argumentNames === void 0 && callHasPositionalArguments(expression) || expression.argumentNames !== void 0 && declaredTarget.constructorSignature.namedProjections !== void 0);
             if (declared.length > 0 && !projectionCall) {
               return this.resolveDeclaredConstructor(
                 className,
@@ -9102,13 +9121,13 @@ var init_strict_resolver = __esm({
                 expression.pos
               );
             }
-            if (expression.argumentNames) {
+            if (expression.argumentNames && !projectionCall) {
               throw new CompileError(
                 "Named constructor arguments require a declaration-aware project source context.",
                 expression.pos
               );
             }
-            if (expression.initializer && expression.initializer.length > 0) {
+            if (expression.initializer && expression.initializer.length > 0 && !projectionCall) {
               throw new CompileError(
                 "Object initializers are available to project source construction and are not executable NeoScript constructors.",
                 expression.pos
@@ -9116,9 +9135,10 @@ var init_strict_resolver = __esm({
             }
             return this.resolveClassConstructor(
               className,
-              expression.args,
+              expression,
               scope,
-              expression.pos
+              expression.pos,
+              expected
             );
           }
           case "annotated":
@@ -9739,6 +9759,12 @@ var init_strict_resolver = __esm({
       }
       resolveMemberNatural(receiverAst, name, scope, pos, optional) {
         if (receiverAst.kind === "ident" && !scope.lookup(receiverAst.name)) {
+          if (receiverAst.name === "SpriteInfo" && name === "Empty") {
+            return literal(
+              { kind: "primitive", name: "SpriteInfo" },
+              { ...NEOSCRIPT_SPRITE_INFO_EMPTY_VALUE }
+            );
+          }
           const staticType = this.project.typeByName.get(receiverAst.name);
           if (staticType && staticType.kind !== "enum") {
             if (optional) {
@@ -9769,6 +9795,11 @@ var init_strict_resolver = __esm({
                 pos
               );
             }
+            if (member.id === NEOSCRIPT_SPRITE_INFO_EMPTY_MEMBER_ID) {
+              return literal(member.type, {
+                ...NEOSCRIPT_SPRITE_INFO_EMPTY_VALUE
+              });
+            }
             if (member.computed === true) {
               return {
                 pointer: {
@@ -10515,7 +10546,7 @@ var init_strict_resolver = __esm({
           type: optional ? { ...delegateType.returnType, nullable: true } : delegateType.returnType
         };
       }
-      resolveClassConstructor(className, argumentsList2, scope, pos) {
+      resolveClassConstructor(className, expression, scope, pos, expected) {
         const schemaClass2 = this.project.typeByName.get(className);
         if (!schemaClass2 || schemaClass2.kind !== "class") {
           throw new CompileError(
@@ -10537,26 +10568,86 @@ var init_strict_resolver = __esm({
             pos
           );
         }
+        const targetType = this.constructorTargetType(
+          schemaClass2,
+          expression,
+          expected
+        );
+        const parameters = signature.parameters.map((parameter3) => ({
+          ...parameter3,
+          valueType: substituteTypeParameters(
+            parameter3.valueType,
+            targetType,
+            schemaClass2
+          ),
+          parameterType: substituteTypeParameters(
+            parameter3.parameterType,
+            targetType,
+            schemaClass2
+          )
+        }));
+        const argumentsList2 = expression.args;
+        const namedProjections = signature.namedProjections;
+        if (expression.argumentNames !== void 0) {
+          if (namedProjections === void 0) {
+            throw new CompileError(
+              `Class '${className}' exposes no named constructor projection.`,
+              pos
+            );
+          }
+          if (argumentsList2.length !== namedProjections.length) {
+            throw new CompileError(
+              `${className} constructor requires ${namedProjections.length} named argument${namedProjections.length === 1 ? "" : "s"} but got ${argumentsList2.length}.`,
+              pos
+            );
+          }
+          if (expression.argumentNames.length !== argumentsList2.length) {
+            throw new CompileError(
+              `${className} constructor projection requires every argument to be named.`,
+              pos
+            );
+          }
+        }
         const requiredCount = signature.parameters.filter(
           (parameter3) => parameter3.required
         ).length;
-        if (argumentsList2.length < requiredCount) {
+        if (expression.argumentNames === void 0 && argumentsList2.length < requiredCount) {
           throw new CompileError(
             `${className} constructor requires ${requiredCount} argument${requiredCount === 1 ? "" : "s"} but got ${argumentsList2.length}.`,
             pos
           );
         }
-        if (argumentsList2.length > signature.parameters.length) {
+        if (expression.argumentNames === void 0 && argumentsList2.length > parameters.length) {
           throw new CompileError(
-            `${className} constructor accepts at most ${signature.parameters.length} argument${signature.parameters.length === 1 ? "" : "s"} but got ${argumentsList2.length}.`,
+            `${className} constructor accepts at most ${parameters.length} argument${parameters.length === 1 ? "" : "s"} but got ${argumentsList2.length}.`,
             pos
           );
         }
         const fields = argumentsList2.map((argument2, index) => {
-          const parameter3 = signature.parameters[index];
+          const projectionName = expression.argumentNames?.[index];
+          const projection = projectionName === void 0 ? void 0 : namedProjections?.find(
+            (candidate) => candidate.name === projectionName
+          );
+          if (projectionName !== void 0 && projection === void 0) {
+            throw new CompileError(
+              `Class '${className}' has no constructor projection named '${projectionName}'.`,
+              argument2.pos
+            );
+          }
+          if (projection !== void 0 && expression.argumentNames?.findIndex(
+            (candidate) => candidate === projection.name
+          ) !== index) {
+            throw new CompileError(
+              `Constructor argument '${projection.name}' is supplied more than once.`,
+              argument2.pos
+            );
+          }
+          const parameter3 = projection === void 0 ? parameters[index] : parameters.find(
+            (candidate) => candidate.memberId === projection.memberId
+          );
           if (!parameter3) {
             throw new Error(
-              `NeoScript constructor ${className} lost parameter ${index + 1} after argument-count validation.`
+              projection === void 0 ? `NeoScript constructor ${className} lost parameter ${index + 1} after argument-count validation.` : `NeoScript constructor ${className} projection '${projection.name}' names missing member '${projection.memberId}'.`
             );
           }
           const value = this.resolveExpression(
@@ -10576,7 +10667,20 @@ var init_strict_resolver = __esm({
             valuePointer: value.pointer
           };
         });
-        const schemaClassInfo = toWireType(signature.returnType, this.project);
+        if (namedProjections !== void 0 && expression.argumentNames !== void 0) {
+          for (const projection of namedProjections) {
+            if (!expression.argumentNames.includes(projection.name)) {
+              throw new CompileError(
+                `${className} constructor is missing named argument '${projection.name}'.`,
+                pos
+              );
+            }
+          }
+        }
+        fields.push(
+          ...this.resolveCallSiteInitializerFields(schemaClass2, expression, scope)
+        );
+        const schemaClassInfo = toWireType(targetType, this.project);
         if (schemaClassInfo.type !== 7 /* Class */) {
           throw new Error(
             `NeoScript constructor ${className} has non-Class return type ${this.describe(signature.returnType)}.`
@@ -10590,10 +10694,35 @@ var init_strict_resolver = __esm({
               info: { schemaClassInfo, fields }
             }
           },
-          type: { ...signature.returnType, nullable: false },
+          type: { ...targetType, nullable: false },
           writability: "session" /* Session */
         };
       }
+      constructorTargetType(schemaClass2, expression, expected) {
+        const typeArguments = expression.typeArguments?.map(
+          (argument2) => this.resolveType(argument2)
+        );
+        if (typeArguments !== void 0 && typeArguments.length !== (schemaClass2.typeParameters?.length ?? 0)) {
+          throw new CompileError(
+            `Class '${schemaClass2.name}' expects ${schemaClass2.typeParameters?.length ?? 0} type argument${schemaClass2.typeParameters?.length === 1 ? "" : "s"} but got ${typeArguments.length}.`,
+            expression.pos
+          );
+        }
+        if (typeArguments !== void 0) {
+          return {
+            kind: "named",
+            typeId: schemaClass2.id,
+            typeArguments
+          };
+        }
+        if (expected?.kind === "named" && expected.typeId === schemaClass2.id) {
+          return { ...expected, nullable: false };
+        }
+        return {
+          kind: "named",
+          typeId: schemaClass2.id
+        };
+      }
       /**
        * P43 §7.1. P29's `new T(id: "…")` projection names a class-default row,
        * which is exactly the wrong identity inside a construction body: member
@@ -38004,10 +38133,10 @@ function isSpriteValue(value) {
   if (!Number.isInteger(sliceIndex)) return false;
   return sliceIndex >= 0;
 }
-function pendingSpriteValue() {
+function emptySpriteValue() {
   return { fileId: "", sliceIndex: 0 };
 }
-function isPendingSpriteValue(value) {
+function isEmptySpriteValue(value) {
   if (!value || typeof value !== "object") return false;
   return getField(value, "fileId") === "" && getField(value, "sliceIndex") === 0;
 }
@@ -38910,6 +39039,7 @@ var init_world_system_classes_generated = __esm({
           {
             memberId: "system_cbd6db9a-f473-44b5-b913-7cdc06452f35",
             memberKind: "sprite",
+            defaultValue: { fileId: "", sliceIndex: 0 },
             required: true,
             schemaKey: "Sprite"
           },
@@ -39032,6 +39162,7 @@ var init_world_system_classes_generated = __esm({
           {
             memberId: "system_e9288ba9-f5a2-4485-8443-6afb155b31e0",
             memberKind: "sprite",
+            defaultValue: { fileId: "", sliceIndex: 0 },
             required: true,
             schemaKey: "Sprite"
           },
@@ -39516,6 +39647,12 @@ var init_world_system_classes_generated = __esm({
         docsText: "One value at a frame index inside a segment. It holds until the next row\nyou author, or until the segment's Duration runs out.",
         extendsWorldKind: "animationFrameBase",
         isAbstract: false,
+        constructorProjections: [
+          {
+            memberId: "system_b71d1f73-da72-49de-ab9a-911cc9bffa43",
+            parameterName: "value"
+          }
+        ],
         genericParams: [
           { id: "system_887b11d3-e56a-47ff-8d01-e2fcefb846a1", name: "T" }
         ],
@@ -42586,7 +42723,7 @@ function stampGenericBindings(value, member, args) {
 }
 function shouldSkipRequiredChildDefault(member) {
   if (member.defaultValue !== void 0) return false;
-  return isMemberSpriteBase(member) || isMemberAudioBase(member);
+  return isMemberAudioBase(member);
 }
 function shouldMaterializeChildDefault(member) {
   if (isMemberClassBase(member) && member.partial === true) return false;
@@ -42658,7 +42795,7 @@ function primitiveFallbackValue(document, member) {
   if (isMemberLookupBase(member)) return { value: [] };
   if (isMemberDialogueLookupBase(member)) return { value: [] };
   if (isMemberSpriteBase(member)) {
-    return { value: pendingSpriteValue() };
+    return { value: emptySpriteValue() };
   }
   if (isMemberAudioBase(member)) {
     return { value: pendingAudioValue() };
@@ -42682,7 +42819,7 @@ function primitiveFallbackValue(document, member) {
 function isPendingFileMemberValue(member, body) {
   const value = body.value;
   if (isMemberSpriteBase(member)) {
-    return isPendingSpriteValue(value);
+    return isEmptySpriteValue(value);
   }
   if (isMemberAudioBase(member)) {
     return isPendingAudioValue(value);
@@ -42768,11 +42905,18 @@ function validateDecimalMemberValue(member, body) {
 }
 function validateSpriteMemberValue(document, member, body) {
   const spriteValue = body.value;
+  if (spriteValue === null) {
+    if (!member.required) return;
+    throw new Error(
+      `Sprite member "${member.name}" is required and cannot be null.`
+    );
+  }
   if (!isSpriteValue(spriteValue)) {
     throw new Error(
       "Sprite value must be { fileId: string, sliceIndex: integer >= 0 }."
     );
   }
+  if (isEmptySpriteValue(spriteValue)) return;
   validateSpriteFileRegistration(document, member, spriteValue.fileId);
 }
 function validateSpriteFileRegistration(document, member, fileId) {
@@ -44456,7 +44600,13 @@ function lowerFieldMember(context, ownerClass, declaration, id2, commonInput, ba
       classId,
       ...partial ? { partial: true } : {},
       schemaKeyOrder: base?.kind === "class" ? base.schemaKeyOrder : null,
-      classArguments: lowerClassArguments(context, ownerClass, id2, fieldType)
+      classArguments: lowerClassArguments(
+        context,
+        ownerClass,
+        id2,
+        fieldType,
+        base?.kind === "class" ? base.classArguments : void 0
+      )
     };
   }
   throw new Error(
@@ -44993,6 +45143,9 @@ function lowerExpressionValue(context, expression, declaredExpected, ownerClass,
   }
   switch (expression.kind) {
     case "litNull":
+      if (!expected.nullable) {
+        throw new Error(`Required value ${path} cannot be null.`);
+      }
       return null;
     case "litBool":
     case "litString":
@@ -45212,6 +45365,9 @@ function lowerExpressionValue(context, expression, declaredExpected, ownerClass,
       );
     }
     case "member": {
+      if (expected.name === "SpriteInfo" && expression.name === "Empty" && expression.receiver.kind === "ident" && expression.receiver.name === "SpriteInfo") {
+        return { fileId: "", sliceIndex: 0 };
+      }
       const fileId = projectFileIdForPath(context, expression);
       if (fileId !== null) return { fileId };
       if (expression.name === "Slice" || expression.receiver.kind === "call") {
@@ -45525,7 +45681,7 @@ function genericParameterName(context, genericParamId) {
   }
   return "object";
 }
-function lowerClassArguments(context, ownerClass, ownerMemberId, type) {
+function lowerClassArguments(context, ownerClass, ownerMemberId, type, baseArguments) {
   const classId = context.classIdsByName.get(type.name);
   if (!classId) return {};
   const parameters = [
@@ -45541,7 +45697,8 @@ function lowerClassArguments(context, ownerClass, ownerMemberId, type) {
       result[parameterId] = { kind: "generic", genericParamId: ownerParameter };
       continue;
     }
-    const memberId = derivedGenericArgumentMemberId(ownerMemberId, parameterId);
+    const baseBinding = baseArguments?.[parameterId];
+    const memberId = baseBinding?.kind === "member" ? baseBinding.memberId : derivedGenericArgumentMemberId(ownerMemberId, parameterId);
     result[parameterId] = { kind: "member", memberId };
     lowerGenericArgument(
       context,
@@ -45561,6 +45718,7 @@ function lowerExtendsBindings(context, declaration, baseClassId, argumentsValue)
   ];
   const result = {};
   const declarationId = materializedId(declaration, "class", declaration.name);
+  const baseBindings = context.baseClasses.get(declarationId)?.extendsGenericBindings ?? {};
   for (const [[parameterName, parameterId], argumentType] of zip(
     parameters,
     argumentsValue
@@ -45570,7 +45728,8 @@ function lowerExtendsBindings(context, declaration, baseClassId, argumentsValue)
       result[parameterId] = { kind: "generic", genericParamId: local };
       continue;
     }
-    const memberId = derivedGenericArgumentMemberId(declarationId, parameterId);
+    const baseBinding = baseBindings[parameterId];
+    const memberId = baseBinding?.kind === "member" ? baseBinding.memberId : derivedGenericArgumentMemberId(declarationId, parameterId);
     result[parameterId] = { kind: "member", memberId };
     lowerGenericArgument(
       context,
@@ -47596,6 +47755,15 @@ function renderDefaultValue(context, member, wrapper) {
         `${member.kind === "sprite" ? "Sprite" : "Audio"} member ${JSON.stringify(member.name)} default stores a file value with no fileId. Emitting it as null would delete the default on the next push.`
       );
     }
+    if (value.fileId.length === 0) {
+      const sliceIndex = typeof value.sliceIndex === "number" ? value.sliceIndex : 0;
+      if (member.kind === "sprite" && sliceIndex === 0) {
+        return "SpriteInfo.Empty";
+      }
+      throw new Error(
+        `${member.kind === "sprite" ? "Sprite" : "Audio"} member ${JSON.stringify(member.name)} default stores an invalid empty file value.`
+      );
+    }
     const symbol = context.fileSymbols.get(value.fileId);
     const target = symbol ?? (member.kind === "sprite" ? `Reference<NeoImage>(id: ${quote(value.fileId)})` : `Reference<NeoAudioClip>(id: ${quote(value.fileId)})`);
     return member.kind === "sprite" ? `${target}.Slice(${typeof value.sliceIndex === "number" ? value.sliceIndex : 0})` : target;
@@ -48532,6 +48700,7 @@ function validateFinalizedFileAssignmentsV4(records2, options = {}) {
       return;
     }
     if (!isObjectRecord2(value)) return;
+    if (isEmptySpriteValue(value)) return;
     if (isStructuredLeafPartialValue(value)) {
       visitSpriteFileField(
         value[STRUCTURED_LEAF_PARTIAL_KEY].fileId,
@@ -52532,7 +52701,10 @@ function classToLanguageType(schemaClass2, context) {
 }
 function constructorSignature(schemaClass2, members, context, genericEnvironment) {
   if (schemaClass2.isAbstract) return {};
-  if (!isClosedClass(schemaClass2.id, context.vm.classes)) return {};
+  const projections = inheritedConstructorProjections(schemaClass2, context);
+  if (projections.length === 0 && !isClosedClass(schemaClass2.id, context.vm.classes)) {
+    return {};
+  }
   if (resolveAllowedStorage(schemaClass2.id, context.vm.classes) === "immutable" /* Immutable */) {
     return { constructorUnavailableReason: "immutableOnly" };
   }
@@ -52553,11 +52725,43 @@ function constructorSignature(schemaClass2, members, context, genericEnvironment
           defaultValue: "defaultValue" in resolved ? resolved.defaultValue : void 0
         };
       } catch {
+        if (projections.some((projection) => projection.memberId === memberId)) {
+          return { required: true };
+        }
         return null;
       }
     }
   );
-  return { constructorSignature: signature };
+  return {
+    constructorSignature: {
+      ...signature,
+      ...projections.length === 0 ? {} : {
+        namedProjections: projections.map((projection) => ({
+          name: projection.parameterName,
+          memberId: projection.memberId
+        }))
+      }
+    }
+  };
+}
+function inheritedConstructorProjections(schemaClass2, context) {
+  const classesById = new Map(
+    context.vm.classes.map((candidate) => [candidate.id, candidate])
+  );
+  const projections = [];
+  const claimed = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  let current = schemaClass2;
+  while (current !== void 0 && !visited.has(current.id)) {
+    visited.add(current.id);
+    for (const projection of current.constructorProjections ?? []) {
+      if (claimed.has(projection.parameterName)) continue;
+      claimed.add(projection.parameterName);
+      projections.push(projection);
+    }
+    current = current.extendsClassId ? classesById.get(current.extendsClassId) : void 0;
+  }
+  return projections;
 }
 function declaredConstructors(schemaClass2, context) {
   const requiredConstructorId2 = schemaClass2.requiredConstructorId;
@@ -54266,13 +54470,37 @@ function throwNamedBodyCompileFailure(args) {
   });
 }
 function resolveMemberDeclaredTypeInfo(member, members) {
+  return resolveMemberDeclaredTypeInfoInternal(member, members, /* @__PURE__ */ new Set());
+}
+function resolveMemberDeclaredTypeInfoInternal(member, members, seen) {
   const resolved = resolveMember2(member, members);
+  const memberId = getField(resolved, "id");
+  if (typeof memberId === "string" && seen.has(memberId)) return null;
+  const nextSeen = typeof memberId === "string" ? /* @__PURE__ */ new Set([...seen, memberId]) : new Set(seen);
   if (isMemberNSPropertyBase(resolved)) return resolved.returnTypeInfo;
   if (isMemberClassBase(resolved)) {
+    const typeArguments = Object.fromEntries(
+      Object.entries(resolved.classArguments ?? {}).flatMap(
+        ([genericParamId, binding]) => {
+          if (binding.kind !== "member") return [];
+          const argumentMember = members.find(
+            (candidate) => candidate.id === binding.memberId
+          );
+          if (argumentMember === void 0) return [];
+          const argumentType = resolveMemberDeclaredTypeInfoInternal(
+            argumentMember,
+            members,
+            nextSeen
+          );
+          return argumentType === null ? [] : [[genericParamId, { ...argumentType, required: true }]];
+        }
+      )
+    );
     return {
       type: 7 /* Class */,
       required: resolved.required,
-      classId: resolved.classId
+      classId: resolved.classId,
+      ...Object.keys(typeArguments).length === 0 ? {} : { typeArguments }
     };
   }
   if (isMemberEnumBase(resolved)) {
@@ -54299,7 +54527,11 @@ function resolveMemberDeclaredTypeInfo(member, members) {
       (candidate) => candidate.id === resolved.entryMemberId
     );
     if (entry === void 0) return null;
-    const entryTypeInfo = resolveMemberDeclaredTypeInfo(entry, members);
+    const entryTypeInfo = resolveMemberDeclaredTypeInfoInternal(
+      entry,
+      members,
+      nextSeen
+    );
     if (entryTypeInfo === null) return null;
     return {
       type: resolved.kind,
@@ -54315,7 +54547,7 @@ function resolveMemberDeclaredTypeInfo(member, members) {
     if (collection === void 0) return null;
     return lookupDeclaredTypeInfo(
       resolved,
-      resolveMemberDeclaredTypeInfo(collection, members)
+      resolveMemberDeclaredTypeInfoInternal(collection, members, nextSeen)
     );
   }
   if (!memberKindSupportsStorage(resolved.kind)) return null;
@@ -75266,15 +75498,16 @@ function replayStoredConstructionV4(args) {
     member: compileMember,
     valueRow: candidate,
     valueId: args.valueId,
-    // P61 instance calls are self-contained and never inherit a declaration's
-    // required-constructor parameter envelope.
-    initializerOwnerClass: null
+    // Instance calls are self-contained. Declaration calls inherit the class
+    // header parameters that are in lexical scope at their source site.
+    initializerOwnerClass: args.initializerOwnerClass ?? null
   });
   if (!isMemberValue(candidate) || !isInitValueContent(candidate)) {
     throw new Error(
       `Construction replay for value "${args.valueId}" did not compile an initializer row.`
     );
   }
+  if (args.evaluate === false) return /* @__PURE__ */ new Map();
   const materialized = materializeInitializerValue({
     document,
     // Constructor-only rows have no structural member owner. Use the same
@@ -76384,7 +76617,7 @@ function lowerRowBackedDefault(context, member, backed, baseData3, binding) {
     const assignmentSlices = objectInitializerSlices(binding.initializer);
     for (const assignment of expression.initializer ?? []) {
       const childMember = classMemberByName(context, classId, assignment.name);
-      if (inheritedConstructorProjections(context.classes, schemaClass2.id).some(
+      if (inheritedConstructorProjections2(context.classes, schemaClass2.id).some(
         (projection) => projection.memberId === childMember.id
       )) {
         throw new Error(
@@ -76797,7 +77030,7 @@ function lowerSeedRow(context, member, sourceExpression, source, valueId, path,
         effectiveClass.id,
         assignment.name
       );
-      if (inheritedConstructorProjections(
+      if (inheritedConstructorProjections2(
         context.classes,
         effectiveClass.id
       ).some((projection) => projection.memberId === childMember.id)) {
@@ -77095,15 +77328,17 @@ function lowerValueRow(context, member, sourceExpression, expectedValueId, sourc
           `Value ${expectedValueId} stores constructor arguments but its declared member ${resolvedMember.name} is not a Class.`
         );
       }
-      context.initializerReconciliations.set(expectedValueId, {
-        valueId: expectedValueId,
-        code,
-        storedConstructorArgs: storedConstructorArgs === null ? null : structuredClone(storedConstructorArgs),
-        settleFields: expression.kind === "new" ? (expression.initializer ?? []).map(
-          (assignment) => assignment.name
-        ) : [],
-        site: referenceSite(source, expression)
-      });
+      if (source.purpose === "stored") {
+        context.initializerReconciliations.set(expectedValueId, {
+          valueId: expectedValueId,
+          code,
+          storedConstructorArgs: storedConstructorArgs === null ? null : structuredClone(storedConstructorArgs),
+          settleFields: expression.kind === "new" ? (expression.initializer ?? []).map(
+            (assignment) => assignment.name
+          ) : [],
+          site: referenceSite(source, expression)
+        });
+      }
       const value2 = lowerClassValue(
         context,
         resolvedMember,
@@ -77143,7 +77378,12 @@ function lowerValueRow(context, member, sourceExpression, expectedValueId, sourc
 }
 function lowerValueBody(context, member, expression, base, source, environment, authoredSlice) {
   const next = valueFileFields(base);
-  if (expression.kind === "litNull") return { ...next, value: null };
+  if (expression.kind === "litNull") {
+    if (member.required) {
+      throw new Error(`Required member ${member.name} cannot store null.`);
+    }
+    return { ...next, value: null };
+  }
   switch (member.kind) {
     case "null":
       return { ...next, value: null };
@@ -77293,7 +77533,7 @@ function lowerClassValue(context, member, expression, base, source, outerEnviron
   }
   for (const assignment of expression.initializer ?? []) {
     const childMember = classMemberByName(context, classId, assignment.name);
-    if (inheritedConstructorProjections(context.classes, schemaClass2.id).some(
+    if (inheritedConstructorProjections2(context.classes, schemaClass2.id).some(
       (projection) => projection.memberId === childMember.id
     )) {
       throw new Error(
@@ -77475,7 +77715,7 @@ function classInheritanceChain(classes, classId) {
   }
   return chain;
 }
-function inheritedConstructorProjections(classes, classId) {
+function inheritedConstructorProjections2(classes, classId) {
   const resolved = [];
   const claimed = /* @__PURE__ */ new Set();
   for (const schemaClass2 of classInheritanceChain(classes, classId)) {
@@ -77496,7 +77736,7 @@ function inheritedProjectionSchemaKey(classes, classId, memberId) {
   return null;
 }
 function resolveConstructorProjectionArguments(context, schemaClass2, expression, ownerValueId, environment, source) {
-  const projections = inheritedConstructorProjections(
+  const projections = inheritedConstructorProjections2(
     context.classes,
     schemaClass2.id
   );
@@ -78127,6 +78367,9 @@ function expressionAnchorPos(expression) {
 }
 function lowerFileValue(context, member, expression) {
   if (member.kind === "sprite") {
+    if (isSpriteInfoEmptyExpression(expression)) {
+      return { fileId: "", sliceIndex: 0 };
+    }
     if (expression.kind !== "call" || expression.callee.kind !== "member" || expression.callee.name !== "Slice") {
       throw new Error(
         `Sprite member ${member.name} requires Image.Slice(index).`
@@ -79114,7 +79357,8 @@ function emitValueBody(context, member, value, visited, targetTyped, environment
       context,
       kind,
       `Audio member ${JSON.stringify(String(member.name ?? member.id))}`,
-      body
+      body,
+      member.required === true
     );
   }
   if (kind === 5)
@@ -79364,7 +79608,12 @@ function storedValueConstructor(context, schemaClass2, constructorArgs) {
   return selected2;
 }
 function storedConstructorArgumentSource(context, type, value, environment, visited, cloneAggregateArguments = false) {
-  if (value === null) return "null";
+  if (value === null) {
+    if (!type.nullable) {
+      throw new Error("Required constructor argument stores null.");
+    }
+    return "null";
+  }
   switch (type.kind) {
     case "null":
       return "null";
@@ -79396,7 +79645,8 @@ function storedConstructorArgumentSource(context, type, value, environment, visi
         {
           id: "__constructor_arg__",
           name: "argument",
-          kind: 11 /* Sprite */
+          kind: 11 /* Sprite */,
+          required: !type.nullable
         },
         value
       );
@@ -79405,7 +79655,8 @@ function storedConstructorArgumentSource(context, type, value, environment, visi
         context,
         12 /* Audio */,
         "constructor argument",
-        value
+        value,
+        !type.nullable
       );
     case "enum":
       return enumValue(
@@ -79790,7 +80041,7 @@ function manifestMemberTypeName(context, member) {
   return fixedSourceTypeNameForKind(member.kind) ?? member.kind;
 }
 function constructorProjectionSource(context, classId, body, visited, environment) {
-  const projections = inheritedConstructorProjections(
+  const projections = inheritedConstructorProjections2(
     context.manifestClasses,
     classId
   );
@@ -80180,8 +80431,13 @@ function delegateValue(context, body) {
   }
   return target.name;
 }
-function fileValue(context, kind, label, body) {
-  if (body === null || body === void 0) return "null";
+function fileValue(context, kind, label, body, required2) {
+  if (body === null || body === void 0) {
+    if (required2) {
+      throw new Error(`${label} is required and cannot store null.`);
+    }
+    return "null";
+  }
   if (!isObjectRecord2(body)) {
     throw new Error(
       `${label} stores ${JSON.stringify(body)}, which is not a file value record.`
@@ -80193,12 +80449,18 @@ function fileValue(context, kind, label, body) {
     );
   }
   if (body.fileId.length === 0) {
-    throw new Error(`${label} stores an empty fileId.`);
+    if (kind === 11 && numberOr2(body.sliceIndex, 0) === 0) {
+      return "SpriteInfo.Empty";
+    }
+    throw new Error(`${label} stores an invalid empty file value.`);
   }
   const base = fileRegistrySource(context, kind, body.fileId);
   if (kind !== 11) return base;
   return `${base}.Slice(${numberOr2(body.sliceIndex, 0)})`;
 }
+function isSpriteInfoEmptyExpression(expression) {
+  return expression.kind === "member" && expression.name === "Empty" && expression.receiver.kind === "ident" && expression.receiver.name === "SpriteInfo";
+}
 function fileRegistrySource(context, kind, fileId) {
   const symbol = context.fileSymbols.get(fileId);
   if (symbol !== void 0) {
@@ -80223,7 +80485,9 @@ function structuredLeafSource(context, kind, member, body) {
 ${assignments.map((entry) => indentNeoSourceNonEmptyLines(entry, 2)).join(",\n")}
 }`;
   }
-  if (kind === 11 /* Sprite */) return fileValue(context, 11, label, body);
+  if (kind === 11 /* Sprite */) {
+    return fileValue(context, 11, label, body, member.required === true);
+  }
   if (body === null) return "null";
   if (!isObjectRecord2(body)) return "new()";
   return `new(${structuredLeafFieldKeys(kind).map((key) => scalar(body[key])).join(", ")})`;
@@ -83940,11 +84204,12 @@ function replayAnimationDeclarationInitializersV4(records2, document) {
   });
   if (initializers.length === 0) return document;
   const rootKinds = /* @__PURE__ */ new Map();
+  const rootOwners = /* @__PURE__ */ new Map();
   const owners = resolveOwnerMembersForValues(
     document,
     new Set(initializers.map(({ row }) => row.id)),
     void 0,
-    void 0,
+    rootOwners,
     rootKinds
   );
   const pulled = /* @__PURE__ */ new Map();
@@ -83969,12 +84234,20 @@ function replayAnimationDeclarationInitializersV4(records2, document) {
     if (!classBelongsToAnimationFamily(document.classes, declaredClassId)) {
       continue;
     }
+    const rootOwner = rootOwners.get(row.id);
+    const rootOwnerId = Reflect.get(rootOwner ?? {}, "id");
+    const initializerOwnerClass = typeof rootOwnerId !== "string" ? null : findSchemaPlacement(rootOwnerId, document.classes)?.ownerClass ?? null;
     const replay = replayStoredConstructionV4({
       records: pulled,
       valueId: row.id,
       code,
       member: owner,
-      compileDocumentBodies: true
+      compileDocumentBodies: true,
+      initializerOwnerClass,
+      // A parameterized declaration is a template. Its arguments exist only
+      // at concrete construction sites, so validate the authored body here
+      // without fabricating values for the class header parameters.
+      evaluate: initializerOwnerClass?.requiredConstructorId === void 0 || initializerOwnerClass.requiredConstructorId === null
     });
     for (const [id2, value] of replay) {
       if (!isMemberValue(value)) {
@@ -84358,6 +84631,7 @@ var init_workspace_status = __esm({
     init_project_documents();
     init_animation_clips();
     init_classes();
+    init_inheritance();
     init_members();
     init_value_row_owner_members();
     init_project2();
@@ -94858,7 +95132,7 @@ async function downloadProjectVersionTransactionResult(args) {
     cursor = page.continueCursor;
   }
 }
-async function runPush(workspace, options) {
+async function preparePushStatus(workspace, options) {
   const status = computeWorkspaceStatus(workspace);
   if (status.conflictedFiles.length > 0) {
     throw new Error(
@@ -94887,22 +95161,7 @@ ${blockingErrors.map((error) => `  ${error.message}`).join("\n")}`
     changes: status.changes,
     binaryChanges: status.binaryChanges ?? []
   });
-  if (status.changes.length === 0) {
-    if (options.json === true) {
-      console.log(
-        JSON.stringify({
-          type: "push-plan",
-          dryRun: options.dryRun,
-          changeCount: 0,
-          staticValueSeedCount: 0,
-          changes: []
-        })
-      );
-    } else {
-      console.log("Nothing to push \u2014 working copy is clean.");
-    }
-    return;
-  }
+  if (status.changes.length === 0) return status;
   const initConversions = status.initConversions ?? [];
   if (initConversions.length > 0 && options.json !== true) {
     for (const line of describeInitConversions(initConversions)) warn(line);
@@ -94974,8 +95233,40 @@ ${blockingErrors.map((error) => `  ${error.message}`).join("\n")}`
     } catch (error) {
       reportDryRunFailure(error, options.json === true);
       process.exitCode = 1;
-      return;
+      return null;
+    }
+  }
+  return status;
+}
+async function runPush(workspace, options, preparationOverride) {
+  const preparation = preparationOverride === void 0 ? process.stdout.isTTY === true && options.json !== true ? spinner("Preparing push\u2026") : null : preparationOverride;
+  let status;
+  try {
+    status = await preparePushStatus(workspace, options);
+  } catch (error) {
+    preparation?.fail("Push preparation failed.");
+    throw error;
+  }
+  if (status === null) {
+    preparation?.fail("Push preparation failed.");
+    return;
+  }
+  preparation?.stop();
+  if (status.changes.length === 0) {
+    if (options.json === true) {
+      console.log(
+        JSON.stringify({
+          type: "push-plan",
+          dryRun: options.dryRun,
+          changeCount: 0,
+          staticValueSeedCount: 0,
+          changes: []
+        })
+      );
+    } else {
+      console.log("Nothing to push \u2014 working copy is clean.");
     }
+    return;
   }
   if (options.json === true) {
     console.log(
@@ -98100,14 +98391,29 @@ async function main() {
       return;
     }
     case "push": {
-      const workspace = loadWorkspaceForCommand(args);
-      const { runPush: runPush2 } = await Promise.resolve().then(() => (init_push(), push_exports));
-      await runPush2(workspace, {
-        dryRun: boolFlag(args, "dry-run"),
-        summary: stringFlag(args, "summary"),
-        acceptBump: boolFlag(args, "accept-bump"),
-        json: boolFlag(args, "json")
-      });
+      const json = boolFlag(args, "json");
+      const preparation = process.stdout.isTTY === true && json !== true ? spinner("Preparing push\u2026") : null;
+      let handedOffPreparation = false;
+      try {
+        const workspace = loadWorkspaceForCommand(args);
+        const { runPush: runPush2 } = await Promise.resolve().then(() => (init_push(), push_exports));
+        handedOffPreparation = true;
+        await runPush2(
+          workspace,
+          {
+            dryRun: boolFlag(args, "dry-run"),
+            summary: stringFlag(args, "summary"),
+            acceptBump: boolFlag(args, "accept-bump"),
+            json
+          },
+          preparation
+        );
+      } catch (error) {
+        if (!handedOffPreparation) {
+          preparation?.fail("Push preparation failed.");
+        }
+        throw error;
+      }
       return;
     }
     case "status": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.21.2",
+  "version": "0.21.4",
   "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.21.2 -->
+<!-- reviewed-through-cli: 0.21.4 -->
 
 # Neo Compose CLI
 

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

@@ -66,12 +66,15 @@ Use complete values in normal member initialization:
 
 ```neo
 Sprite = Images.Hero.Slice(0);
+Placeholder = SpriteInfo.Empty;
 Position = new(0, 0, 0);
 Tint = Color(1, 1, 1, 1);
 ```
 
 A bare `Images.Hero` yields a file ID only in a file-valued field context.
 Use `.Slice(index)` for a complete `SpriteInfo`.
+Use `SpriteInfo.Empty` for an authored non-null empty sprite. Use `null` only
+when the declared type is nullable `SpriteInfo?`.
 
 NeoScript may read or write structured fields when the receiver's effective
 storage permits it:

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

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

package/skills/neocompose-cli/references/commands-and-sync.md

@@ -37,6 +37,10 @@ validation — so a rejection that used to cost a real push and return an opaque
 `preparation-failed` now reports before anything is sent. It does not prompt,
 upload, commit, or rewrite source.
 
+Interactive pushes show `Preparing push…` before workspace discovery,
+lowering, and compilation begin. JSON and non-TTY output remain structured and
+do not emit that terminal-only spinner.
+
 A clean dry-run does not promise a clean push. The workspace holds its
 last-pulled state, so everything that grades the live head is still server-only:
 re-verification of the uploaded bundle bytes, project-file staging, the