@neocompose/cli 0.21.2 → 0.21.3

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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

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") {
@@ -77143,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 };
@@ -78127,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).`
@@ -79114,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)
@@ -79364,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";
@@ -79396,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
       );
@@ -79405,7 +79470,8 @@ function storedConstructorArgumentSource(context, type, value, environment, visi
         context,
         12 /* Audio */,
         "constructor argument",
-        value
+        value,
+        !type.nullable
       );
     case "enum":
       return enumValue(
@@ -80180,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.`
@@ -80193,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) {
@@ -80223,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(", ")})`;
@@ -94858,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(
@@ -94887,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);
@@ -94974,9 +95038,41 @@ ${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(
       JSON.stringify({
@@ -98100,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.2",
+  "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.2 -->
+<!-- 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.2 -->
+<!-- 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