@neocompose/cli 0.21.1 → 0.21.3

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [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
+
+- Canonical pull emits `@id` only for structurally ambiguous positions such
+  as list entries. Class fields, dictionary entries, and constructor arguments
+  recover their value rows from the owning value and role instead of exposing
+  redundant P61 creation or localization-link identities.
+- Long and nested constructor calls emitted by `neo pull --reset` wrap at a
+  stable 88-column default with one named argument per indented line.
+
 ## [0.21.1] - 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"),
@@ -9739,6 +9757,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 +9793,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: {
@@ -38004,10 +38033,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 +38939,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 +39062,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 +39547,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 +42623,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 +42695,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 +42719,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 +42805,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) {
@@ -44993,6 +45037,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 +45259,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") {
@@ -75392,7 +75442,6 @@ function buildValueEmitContext(records2, manifest) {
       )
     ),
     fileSymbols: projectFileSymbols(records2),
-    referencedValueIds: externallyReferencedValueIds(records2),
     localizedTextIds: /* @__PURE__ */ new Set(),
     constructionReplays: /* @__PURE__ */ new Map()
   };
@@ -77144,7 +77193,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 };
@@ -78128,6 +78182,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).`
@@ -79115,7 +79172,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)
@@ -79235,7 +79293,10 @@ function classValue(context, member, value, visited, targetTyped, outerEnvironme
       `${key} = ${emitValue(context, emittedChildMember, childId, {
         environment,
         definitionSite: !context.symbolsByValueId.has(childId),
-        writeIdentity: !context.symbolsByValueId.has(childId) && context.referencedValueIds.has(childId),
+        // A class slot recovers this row from the owning value and schema key.
+        // P61 creation metadata and localization back-pointers must not turn
+        // that structural child into an explicitly identified source value.
+        writeIdentity: false,
         visited
       })}`
     );
@@ -79245,7 +79306,7 @@ function classValue(context, member, value, visited, targetTyped, outerEnvironme
 ${fields.map((field) => indentNeoSourceNonEmptyLines(field, 2)).join(",\n")}
 }`;
   }
-  const constructor2 = storedConstruction !== null ? storedConstruction : projection.arguments.length > 0 ? `new ${name}(${projection.arguments.join(", ")})` : targetTyped ? "new()" : `new ${name}()`;
+  const constructor2 = storedConstruction !== null ? storedConstruction : projection.arguments.length > 0 ? constructorCallSource(`new ${name}`, projection.arguments) : targetTyped ? "new()" : `new ${name}()`;
   return fields.length === 0 ? constructor2 : `${storedConstruction !== null || projection.arguments.length > 0 ? constructor2 : targetTyped ? "new()" : `new ${name}`} {
 ${fields.map((field) => indentNeoSourceNonEmptyLines(field, 2)).join(",\n")}
 }`;
@@ -79322,7 +79383,16 @@ function storedConstructorCallSource(context, schemaClass2, value, className, en
       cloneAggregateArguments
     )}`;
   });
-  return argumentsValue.length === 0 && targetTyped ? "new()" : `new ${className}(${argumentsValue.join(", ")})`;
+  return argumentsValue.length === 0 && targetTyped ? "new()" : constructorCallSource(`new ${className}`, argumentsValue);
+}
+function constructorCallSource(callee, argumentsValue) {
+  const inline = `${callee}(${argumentsValue.join(", ")})`;
+  if (!argumentsValue.some((argument2) => argument2.includes("\n")) && inline.length <= CANONICAL_CONSTRUCTOR_INLINE_WIDTH) {
+    return inline;
+  }
+  return `${callee}(
+${argumentsValue.map((argument2) => `${indentNeoSourceNonEmptyLines(argument2, 2)},`).join("\n")}
+)`;
 }
 function storedValueConstructor(context, schemaClass2, constructorArgs) {
   const requiredId = schemaClass2.requiredConstructorId;
@@ -79353,7 +79423,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";
@@ -79385,7 +79460,8 @@ function storedConstructorArgumentSource(context, type, value, environment, visi
         {
           id: "__constructor_arg__",
           name: "argument",
-          kind: 11 /* Sprite */
+          kind: 11 /* Sprite */,
+          required: !type.nullable
         },
         value
       );
@@ -79394,7 +79470,8 @@ function storedConstructorArgumentSource(context, type, value, environment, visi
         context,
         12 /* Audio */,
         "constructor argument",
-        value
+        value,
+        !type.nullable
       );
     case "enum":
       return enumValue(
@@ -79419,7 +79496,14 @@ function storedConstructorArgumentSource(context, type, value, environment, visi
       if (cloneAggregateArguments) {
         return storedAggregateCloneSource(context, type, value, environment);
       }
-      return storedTypedRowSource(context, type, value, environment, visited);
+      return storedTypedRowSource(
+        context,
+        type,
+        value,
+        environment,
+        visited,
+        false
+      );
     }
     case "interface":
     case "generic":
@@ -79433,7 +79517,14 @@ function storedConstructorArgumentSource(context, type, value, environment, visi
       if (cloneAggregateArguments) {
         return storedAggregateCloneSource(context, type, value, environment);
       }
-      return storedTypedRowSource(context, type, value, environment, visited);
+      return storedTypedRowSource(
+        context,
+        type,
+        value,
+        environment,
+        visited,
+        false
+      );
     case "lookup":
       return referenceValue(
         context,
@@ -79552,7 +79643,7 @@ function storedSchemaTypeName(context, type, environment, valueId) {
       return "null";
   }
 }
-function storedTypedRowSource(context, type, valueId, environment, visited) {
+function storedTypedRowSource(context, type, valueId, environment, visited, writeIdentity) {
   const symbol = context.symbolsByValueId.get(valueId);
   if (symbol !== void 0) return symbol;
   const row = context.values.get(valueId);
@@ -79575,32 +79666,34 @@ function storedTypedRowSource(context, type, valueId, environment, visited) {
           `Stored ${type.kind} constructor argument ${valueId} has no concrete class.`
         );
       }
-      return `@id(${quote4(valueId)})
-${classValue(
-        context,
-        {
-          id: `__constructor_arg__:${valueId}`,
-          name: "argument",
-          kind: 7 /* Class */,
-          classId,
-          classArguments: {},
-          partial: false
-        },
-        row,
-        visited,
-        false,
-        environment
-      )}`;
+      return storedRowIdentitySource(
+        valueId,
+        writeIdentity,
+        classValue(
+          context,
+          {
+            id: `__constructor_arg__:${valueId}`,
+            name: "argument",
+            kind: 7 /* Class */,
+            classId,
+            classArguments: {},
+            partial: false
+          },
+          row,
+          visited,
+          false,
+          environment
+        )
+      );
     }
     if (type.kind === "list") {
-      if (row.value === null) return "null";
+      if (row.value === null) {
+        return storedRowIdentitySource(valueId, writeIdentity, "null");
+      }
       const ids = Array.isArray(row.value) ? row.value.filter(
         (entry) => typeof entry === "string"
       ) : [...context.values].filter(([, candidate]) => candidate.containerId === valueId).map(([id2]) => id2).sort(compareCodePoints);
-      if (ids.length === 0) return `@id(${quote4(valueId)})
-[]`;
-      return `@id(${quote4(valueId)})
-[
+      const expression = ids.length === 0 ? "[]" : `[
 ${ids.map(
         (id2) => indentNeoSourceNonEmptyLines(
           storedTypedRowSource(
@@ -79608,22 +79701,26 @@ ${ids.map(
             type.entryType,
             id2,
             environment,
-            visited
+            visited,
+            true
           ),
           2
         )
       ).join(",\n\n")}
 ]`;
+      return storedRowIdentitySource(valueId, writeIdentity, expression);
     }
     if (type.kind === "dictionary") {
-      if (row.value === null) return "null";
-      if (!isObjectRecord2(row.value)) return "{}";
+      if (row.value === null) {
+        return storedRowIdentitySource(valueId, writeIdentity, "null");
+      }
+      if (!isObjectRecord2(row.value)) {
+        return storedRowIdentitySource(valueId, writeIdentity, "{}");
+      }
       const entries = Object.entries(row.value).sort(
         ([left], [right]) => compareCodePoints(left, right)
       );
-      return entries.length === 0 ? `@id(${quote4(valueId)})
-{}` : `@id(${quote4(valueId)})
-{
+      const expression = entries.length === 0 ? "{}" : `{
 ${entries.flatMap(
         ([key, id2]) => typeof id2 === "string" ? [
           indentNeoSourceNonEmptyLines(
@@ -79632,53 +79729,71 @@ ${entries.flatMap(
               type.entryType,
               id2,
               environment,
-              visited
+              visited,
+              false
             )}`,
             2
           )
         ] : []
       ).join(",\n")}
 }`;
+      return storedRowIdentitySource(valueId, writeIdentity, expression);
     }
     if (type.kind === "lookup") {
-      return referenceValue(
-        context,
-        {
-          id: `__constructor_arg__:${valueId}`,
-          name: "argument",
-          kind: 9 /* Lookup */,
-          collectionMemberId: type.collectionMemberId,
-          collectionValueId: type.collectionValueId,
-          multiselect: false
-        },
-        row.value,
-        false
+      return storedRowIdentitySource(
+        valueId,
+        writeIdentity,
+        referenceValue(
+          context,
+          {
+            id: `__constructor_arg__:${valueId}`,
+            name: "argument",
+            kind: 9 /* Lookup */,
+            collectionMemberId: type.collectionMemberId,
+            collectionValueId: type.collectionValueId,
+            multiselect: false
+          },
+          row.value,
+          false
+        )
       );
     }
     if (type.kind === "dialogueLookup") {
-      return referenceValue(
-        context,
-        {
-          id: `__constructor_arg__:${valueId}`,
-          name: "argument",
-          kind: 18 /* DialogueLookup */,
-          multiselect: false
-        },
-        row.value,
-        true
+      return storedRowIdentitySource(
+        valueId,
+        writeIdentity,
+        referenceValue(
+          context,
+          {
+            id: `__constructor_arg__:${valueId}`,
+            name: "argument",
+            kind: 18 /* DialogueLookup */,
+            multiselect: false
+          },
+          row.value,
+          true
+        )
       );
     }
-    return storedConstructorArgumentSource(
-      context,
-      type,
-      row.value,
-      environment,
-      visited
+    return storedRowIdentitySource(
+      valueId,
+      writeIdentity,
+      storedConstructorArgumentSource(
+        context,
+        type,
+        row.value,
+        environment,
+        visited
+      )
     );
   } finally {
     visited.delete(valueId);
   }
 }
+function storedRowIdentitySource(valueId, writeIdentity, expression) {
+  return `${writeIdentity ? `@id(${quote4(valueId)})
+` : ""}${expression}`;
+}
 function storedVectorSource(value, name, keys) {
   if (!isObjectRecord2(value)) {
     throw new Error(`Stored ${name} constructor argument is not an object.`);
@@ -80001,7 +80116,9 @@ ${entries.flatMap(
         `${quote4(key)}: ${emitValue(context, entryMember, id2, {
           environment,
           definitionSite: !context.symbolsByValueId.has(id2),
-          writeIdentity: !context.symbolsByValueId.has(id2) && context.referencedValueIds.has(id2),
+          // Dictionary keys, like class schema keys, recover entry
+          // identity from the owning row. Only list entries need an id.
+          writeIdentity: false,
           visited
         })}`,
         2
@@ -80129,8 +80246,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.`
@@ -80142,12 +80264,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) {
@@ -80172,7 +80300,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(", ")})`;
@@ -80215,33 +80345,6 @@ function projectFileSymbols(records2) {
   });
   return assignDeterministicFileSymbols(files);
 }
-function externallyReferencedValueIds(records2) {
-  const counts = /* @__PURE__ */ new Map();
-  const visit = (value) => {
-    if (typeof value === "string") {
-      if (records2.has(`value:${value}`))
-        counts.set(value, (counts.get(value) ?? 0) + 1);
-      return;
-    }
-    if (Array.isArray(value)) {
-      value.forEach((entry) => visit(entry));
-      return;
-    }
-    if (isObjectRecord2(value)) {
-      for (const [childKey, child] of Object.entries(value)) {
-        if (childKey === "id") continue;
-        if (childKey === "sourceValueId") continue;
-        visit(child);
-      }
-    }
-  };
-  for (const record3 of records2.values()) {
-    if (!record3.deleted) visit(record3.data);
-  }
-  return new Set(
-    [...counts].filter(([, count]) => count > 1).map(([id2]) => id2)
-  );
-}
 function projectMainLocale(records2) {
   const config = [...records2.values()].find(
     (record3) => !record3.deleted && record3.recordKind === "localization-config"
@@ -80330,7 +80433,7 @@ function memberDefaultBody(member) {
   if (!("value" in defaultValue)) return null;
   return defaultValue.value;
 }
-var INFERRED_GENERIC_CLASS_PREFIX, MEMBER_KIND_DICTIONARY, MEMBER_KIND_LIST, MEMBER_KIND_CLASS;
+var INFERRED_GENERIC_CLASS_PREFIX, MEMBER_KIND_DICTIONARY, MEMBER_KIND_LIST, MEMBER_KIND_CLASS, CANONICAL_CONSTRUCTOR_INLINE_WIDTH;
 var init_value_sources = __esm({
   "src/project-source/value-sources.ts"() {
     "use strict";
@@ -80356,6 +80459,7 @@ var init_value_sources = __esm({
     MEMBER_KIND_DICTIONARY = 5;
     MEMBER_KIND_LIST = 6;
     MEMBER_KIND_CLASS = 7;
+    CANONICAL_CONSTRUCTOR_INLINE_WIDTH = 88;
   }
 });
 
@@ -94833,7 +94937,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(
@@ -94862,22 +94966,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);
@@ -94949,8 +95038,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(
@@ -98075,14 +98196,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.1",
+  "version": "0.21.3",
   "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.1 -->
+<!-- reviewed-through-cli: 0.21.3 -->
 
 # 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.1 -->
+<!-- reviewed-through-cli: 0.21.3 -->
 ```
 
 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