@neocompose/cli 0.31.7 → 0.31.9

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.31.9] - 2026-08-17
+
+### Added
+
+- Surface `SpriteInfo.Empty` in project-source and NeoScript completion and
+  hover with documentation for its canonical empty-sprite behavior.
+
+### Fixed
+
+- Accept the exact `SpriteInfo.Empty` sentinel as the non-null result of a
+  required Sprite function while continuing to reject malformed empty sprites
+  and empty Audio values.
+
+## [0.31.8] - 2026-08-17
+
+### Fixed
+
+- Propagate `?.` through following required member and index accesses in the
+  same expression chain, so a nullable parent safely short-circuits a deep
+  read while independently nullable descendants still require explicit null
+  handling.
+
 ## [0.31.7] - 2026-08-15
 
 ### Fixed

package/dist/neo.mjs

@@ -1663,13 +1663,14 @@ var init_language_spec = __esm({
         id: "builtin:SpriteInfo",
         name: "SpriteInfo",
         kind: "builtin",
+        documentation: "A sprite asset reference and slice index. Use SpriteInfo.Empty when a required sprite should render no image.",
         members: [
           {
             ...property(
               "SpriteInfo",
               "Empty",
               SPRITE_INFO_TYPE,
-              "An authored empty sprite at slice zero."
+              "The canonical non-null empty sprite. Use it when a required SpriteInfo should render no image; it has no backing file and uses slice index 0."
             ),
             static: true
           },
@@ -2319,7 +2320,11 @@ function complete(snapshot, position) {
         word
       );
     } else {
-      const resolved = resolveChain(snapshot, receiverTokens, offset);
+      const directStaticType = receiverTokens.length === 1 && receiverTokens[0]?.kind === "type" ? snapshot.project.typeByName.get(receiverTokens[0].text) : void 0;
+      const resolved = directStaticType ? {
+        type: { kind: "named", typeId: directStaticType.id },
+        staticType: directStaticType
+      } : resolveChain(snapshot, receiverTokens, offset);
       candidates = completionItemsForResolution(snapshot, resolved, word);
     }
   } else if (tail?.kind === "identifier" && tail.text === NEOSCRIPT_CONSTRUCTOR_KEYWORD) {
@@ -2343,27 +2348,14 @@ function complete(snapshot, position) {
 function hover(snapshot, position) {
   const offset = snapshot.source.offsetAt(position);
   const reference2 = referenceAt(snapshot.parsed.references, offset);
-  if (!reference2) return null;
+  if (!reference2) return builtinStaticMemberHoverAt(snapshot, offset);
   const resolution = resolveReference(snapshot, reference2);
-  if (!resolution?.symbol && !resolution?.staticType) return null;
+  if (!resolution?.symbol && !resolution?.staticType) {
+    return builtinStaticMemberHoverAt(snapshot, offset);
+  }
   const symbol = resolution.symbol;
   if (symbol) {
-    const signature = formatSymbolSignature(symbol, snapshot.project);
-    const origin = symbol.inheritedFrom ? `
-
-Inherited from \`${symbol.inheritedFrom.typeName}\`.` : "";
-    const identity2 = symbol.id.startsWith("local:") || symbol.id.startsWith("parameter:") ? "" : `
-
-Schema id: \`${symbol.id}\``;
-    const docs2 = symbol.documentation ? `
-
-${symbol.documentation}` : "";
-    return {
-      range: reference2.range,
-      markdown: `**${symbol.name}** _${displaySymbolKind(symbol)}_
-
-\`${signature}\`${docs2}${origin}${identity2}`
-    };
+    return symbolHover(symbol, reference2.range, snapshot.project);
   }
   const type = resolution.staticType;
   if (!type) return null;
@@ -2380,6 +2372,39 @@ ${type.documentation}` : "";
 Schema id: \`${type.id}\`${docs}`
   };
 }
+function symbolHover(symbol, range2, project) {
+  const signature = formatSymbolSignature(symbol, project);
+  const origin = symbol.inheritedFrom ? `
+
+Inherited from \`${symbol.inheritedFrom.typeName}\`.` : "";
+  const identity2 = symbol.id.startsWith("local:") || symbol.id.startsWith("parameter:") ? "" : `
+
+Schema id: \`${symbol.id}\``;
+  const docs = symbol.documentation ? `
+
+${symbol.documentation}` : "";
+  return {
+    range: range2,
+    markdown: `**${symbol.name}** _${displaySymbolKind(symbol)}_
+
+\`${signature}\`${docs}${origin}${identity2}`
+  };
+}
+function builtinStaticMemberHoverAt(snapshot, offset) {
+  const tokens = snapshot.lexed.tokens;
+  const memberIndex = tokens.findIndex(
+    (token) => token.kind === "identifier" && token.start <= offset && offset <= token.end
+  );
+  if (memberIndex < 2 || tokens[memberIndex - 1]?.text !== ".") return null;
+  const owner = tokens[memberIndex - 2];
+  const memberToken = tokens[memberIndex];
+  if (owner?.kind !== "type" || !memberToken) return null;
+  const type = snapshot.project.typeByName.get(owner.text);
+  const member = type?.members.find(
+    (candidate) => candidate.static === true && candidate.name === memberToken.text
+  );
+  return member ? symbolHover(member, memberToken.range, snapshot.project) : null;
+}
 function definition(snapshot, position) {
   const offset = snapshot.source.offsetAt(position);
   const reference2 = referenceAt(snapshot.parsed.references, offset);
@@ -11838,13 +11863,15 @@ var init_strict_resolver = __esm({
             };
           }
         }
-        const receiver = this.resolveExpression(receiverAst, scope);
-        if (optional && !isNullable(receiver.type)) {
+        const resolvedReceiver = this.resolveExpression(receiverAst, scope);
+        if (optional && !isNullable(resolvedReceiver.type)) {
           throw new CompileError(
-            `\`?.\` requires an optional receiver; got ${this.describe(receiver.type)}`,
+            `\`?.\` requires an optional receiver; got ${this.describe(resolvedReceiver.type)}`,
             pos
           );
         }
+        const receiver = resolvedReceiver.optionalChainType ? { ...resolvedReceiver, type: resolvedReceiver.optionalChainType } : resolvedReceiver;
+        const nullPropagating = optional || resolvedReceiver.optionalChainType !== void 0;
         if (!optional && isNullable(receiver.type)) {
           throw new CompileError(
             `Member '${name}' is read on ${this.describe(receiver.type)}, which may be null. Handle null before reading through it \u2014 use \`!\` if it is always set, or \`?.\`, \`??\`, or a null check that narrows it.`,
@@ -11852,7 +11879,7 @@ var init_strict_resolver = __esm({
           );
         }
         if (receiver.staticType?.kind === "enum") {
-          if (optional) {
+          if (nullPropagating) {
             throw new CompileError(
               `\`?.\` is not valid on enum type '${receiver.staticType.name}'; enum option access is always defined`,
               pos
@@ -11924,9 +11951,10 @@ var init_strict_resolver = __esm({
                   pointer: receiver.pointer,
                   key: numberPointer(0)
                 },
-                ...optional ? { optional: true } : {}
+                ...nullPropagating ? { optional: true } : {}
               },
-              type: optional ? { ...primitiveMember.type, nullable: true } : primitiveMember.type,
+              type: nullPropagating ? { ...primitiveMember.type, nullable: true } : primitiveMember.type,
+              ...nullPropagating ? { optionalChainType: primitiveMember.type } : {},
               ...receiver.writability ? { writability: receiver.writability } : {}
             };
           }
@@ -11934,7 +11962,7 @@ var init_strict_resolver = __esm({
             receiver,
             primitiveMember.key ?? name,
             primitiveMember.type,
-            optional
+            nullPropagating
           );
           if (!primitiveMember.derived) return resolved;
           return {
@@ -11968,7 +11996,7 @@ var init_strict_resolver = __esm({
               receiver,
               name,
               { kind: "primitive", name: "string" },
-              optional
+              nullPropagating
             );
           }
           const member = type.members.find((candidate) => candidate.name === name);
@@ -12002,9 +12030,10 @@ var init_strict_resolver = __esm({
                 type: "callGetter" /* CallGetter */,
                 memberId: member.id,
                 receiver: { kind: "instance", pointer: receiver.pointer },
-                ...optional ? { optional: true } : {}
+                ...nullPropagating ? { optional: true } : {}
               },
-              type: optional ? { ...memberType2, nullable: true } : memberType2,
+              type: nullPropagating ? { ...memberType2, nullable: true } : memberType2,
+              ...nullPropagating ? { optionalChainType: memberType2 } : {},
               symbol: member,
               ...member.writable ? {
                 writability: member.writability ? toWritability(member.writability) : "setter" /* Setter */
@@ -12028,7 +12057,7 @@ var init_strict_resolver = __esm({
               receiver,
               member.schemaKey ?? member.name,
               memberType2,
-              optional,
+              nullPropagating,
               member.id
             ),
             symbol: member,
@@ -12136,14 +12165,23 @@ var init_strict_resolver = __esm({
             ...optional ? { optional: true } : {}
           },
           type: optional ? { ...type, nullable: true } : type,
+          ...optional ? { optionalChainType: type } : {},
           ...receiver.writability ? { writability: receiver.writability } : {}
         };
       }
       resolveIndex(receiverAst, indexAst, scope, pos, optional) {
-        const receiver = this.resolveExpression(receiverAst, scope);
-        if (optional && !isNullable(receiver.type)) {
+        const resolvedReceiver = this.resolveExpression(receiverAst, scope);
+        if (optional && !isNullable(resolvedReceiver.type)) {
+          throw new CompileError(
+            `\`?.[]\` requires an optional receiver; got ${this.describe(resolvedReceiver.type)}`,
+            pos
+          );
+        }
+        const receiver = resolvedReceiver.optionalChainType ? { ...resolvedReceiver, type: resolvedReceiver.optionalChainType } : resolvedReceiver;
+        const nullPropagating = optional || resolvedReceiver.optionalChainType !== void 0;
+        if (!optional && isNullable(receiver.type)) {
           throw new CompileError(
-            `\`?.[]\` requires an optional receiver; got ${this.describe(receiver.type)}`,
+            `Index access is read on ${this.describe(receiver.type)}, which may be null. Handle null before indexing it \u2014 use \`!\` if it is always set, or \`?.[]\`, \`??\`, or a null check that narrows it.`,
             pos
           );
         }
@@ -12185,9 +12223,10 @@ var init_strict_resolver = __esm({
               pointer: {
                 type: "keyOf" /* KeyOf */,
                 keyOf: { pointer: receiver.pointer, key: requested.pointer },
-                ...optional ? { optional: true } : {}
+                ...nullPropagating ? { optional: true } : {}
               },
-              type: optional ? { ...receiver.type.elementType, nullable: true } : receiver.type.elementType,
+              type: nullPropagating ? { ...receiver.type.elementType, nullable: true } : receiver.type.elementType,
+              ...nullPropagating ? { optionalChainType: receiver.type.elementType } : {},
               ...receiver.writability ? { writability: receiver.writability } : {}
             };
           }
@@ -12218,9 +12257,10 @@ var init_strict_resolver = __esm({
           pointer: {
             type: "keyOf" /* KeyOf */,
             keyOf: { pointer: receiver.pointer, key: index.pointer },
-            ...optional ? { optional: true } : {}
+            ...nullPropagating ? { optional: true } : {}
           },
-          type: optional ? { ...valueType, nullable: true } : valueType,
+          type: nullPropagating ? { ...valueType, nullable: true } : valueType,
+          ...nullPropagating ? { optionalChainType: valueType } : {},
           ...receiver.writability ? { writability: receiver.writability } : {}
         };
       }
@@ -27285,6 +27325,16 @@ function projectCompletions(analysis, document, position) {
     position
   );
   if (annotations) return { isIncomplete: false, items: annotations };
+  const builtinMembers = projectBuiltinStaticMemberCompletions(
+    document,
+    position
+  );
+  if (builtinMembers) {
+    return {
+      isIncomplete: false,
+      items: builtinMembers.map(projectBuiltinCompletionItem)
+    };
+  }
   const members = projectMemberCompletions(analysis, document, position);
   const variantScope = variantScopeInBody;
   if (members || variantScope) {
@@ -27785,20 +27835,8 @@ function sourceTypeAt(document, position) {
   return null;
 }
 function projectMemberCompletions(analysis, document, position) {
-  const tokens = projectTokens(document).filter(
-    (token) => token.kind !== "eof" && token.kind !== "comment" && // Auto-inserted/future punctuation at the cursor has not been authored
-    // yet for completion purposes. Including a semicolon that starts at the
-    // cursor makes `Device.|;` lose the dot it is completing.
-    positionCompare2(token.range.start, position) < 0
-  );
-  let cursor = tokens.length - 1;
-  const current = tokens[cursor];
-  if (current?.kind === "identifier" && current.range.start.line === position.line) {
-    cursor--;
-  }
-  if (tokens[cursor]?.text !== ".") return null;
-  const owner = tokens[cursor - 1];
-  if (!owner || owner.kind !== "identifier") return null;
+  const owner = projectMemberCompletionOwnerToken(document, position);
+  if (!owner) return null;
   const resolvedOwner = projectSymbolAt(analysis, document, owner.range.start);
   if (!resolvedOwner) return null;
   const ownerNames = projectReceiverOwnerNames(analysis, resolvedOwner.symbol);
@@ -27816,6 +27854,71 @@ function projectMemberCompletions(analysis, document, position) {
   }
   return members.length > 0 ? members : null;
 }
+function projectMemberCompletionOwnerToken(document, position) {
+  const tokens = projectTokens(document).filter(
+    (token) => token.kind !== "eof" && token.kind !== "comment" && // Auto-inserted/future punctuation at the cursor has not been authored
+    // yet for completion purposes. Including a semicolon that starts at the
+    // cursor makes `Device.|;` lose the dot it is completing.
+    positionCompare2(token.range.start, position) < 0
+  );
+  let cursor = tokens.length - 1;
+  const current = tokens[cursor];
+  if (current?.kind === "identifier" && current.range.start.line === position.line) {
+    cursor--;
+  }
+  if (tokens[cursor]?.text !== ".") return null;
+  const owner = tokens[cursor - 1];
+  if (!owner || owner.kind !== "identifier" && owner.kind !== "type") {
+    return null;
+  }
+  return owner;
+}
+function projectBuiltinStaticMemberCompletions(document, position) {
+  const owner = projectMemberCompletionOwnerToken(document, position);
+  if (!owner) return null;
+  const type = NEOSCRIPT_BUILTIN_TYPE_SYMBOLS.find(
+    (candidate) => candidate.name === owner.text
+  );
+  if (!type) return null;
+  const members = type.members.filter((member) => member.static === true);
+  return members.length > 0 ? members : null;
+}
+function projectBuiltinCompletionItem(symbol) {
+  return {
+    label: symbol.name,
+    kind: projectBuiltinCompletionKind(symbol),
+    detail: projectBuiltinSymbolSignature(symbol),
+    ...symbol.documentation ? { documentation: symbol.documentation } : {},
+    insertText: symbol.name,
+    symbolId: symbol.id
+  };
+}
+function projectBuiltinCompletionKind(symbol) {
+  switch (symbol.kind) {
+    case "property":
+    case "field":
+      return "property";
+    case "method":
+      return "method";
+    case "function":
+      return "function";
+    case "enumMember":
+      return "enumMember";
+    default:
+      return "value";
+  }
+}
+function projectBuiltinSymbolSignature(symbol) {
+  if (symbol.parameters !== void 0) {
+    const parameters = symbol.parameters.map((parameter4) => `${formatType(parameter4.type)} ${parameter4.name}`).join(", ");
+    return `${formatType(symbol.returnType ?? symbol.type)} ${symbol.name}(${parameters})`;
+  }
+  if (symbol.kind === "property" || symbol.kind === "field") {
+    const setter = symbol.writable ? " set;" : "";
+    return `${formatType(symbol.type)} ${symbol.name} { get;${setter} }`;
+  }
+  return `${formatType(symbol.type)} ${symbol.name}`;
+}
 function projectConstructorArgumentCompletions(analysis, document, position) {
   const tokens = tokensBeforePosition(document.text, position);
   const openIndex = activeCallOpenIndex(tokens, position);
@@ -28187,6 +28290,31 @@ function projectHover(analysis, document, position) {
   }
   const body = projectBodySnapshotAt(analysis, document, position);
   if (body) return hover(body, position);
+  const builtin = projectBuiltinSymbolAt(document, position);
+  if (builtin) {
+    if (builtin.symbol) {
+      const documentation3 = builtin.symbol.documentation ? `
+
+${builtin.symbol.documentation}` : "";
+      return {
+        range: builtin.token.range,
+        markdown: `**${builtin.symbol.name}** _${builtin.symbol.kind}_
+
+\`${projectBuiltinSymbolSignature(builtin.symbol)}\`${documentation3}
+
+Schema id: \`${builtin.symbol.id}\``
+      };
+    }
+    const documentation2 = builtin.type.documentation ? `
+
+${builtin.type.documentation}` : "";
+    return {
+      range: builtin.token.range,
+      markdown: `**${builtin.type.name}** _${builtin.type.kind}_${documentation2}
+
+Schema id: \`${builtin.type.id}\``
+    };
+  }
   const resolved = projectSymbolAt(analysis, document, position);
   if (!resolved) return null;
   const owner = resolved.symbol.ownerName ? ` on \`${resolved.symbol.ownerName}\`` : "";
@@ -28203,6 +28331,30 @@ ID: \`${resolved.symbol.id}\`` : "\n\nPending ID";
     markdown: `**${resolved.symbol.kind}** \`${resolved.symbol.name}\`${detail}${owner}${documentation}${contract}${id2}`
   };
 }
+function projectBuiltinSymbolAt(document, position) {
+  const token = projectTokenAt(document, position);
+  if (!token || token.kind !== "identifier" && token.kind !== "type") {
+    return null;
+  }
+  const tokens = projectTokens(document);
+  const tokenIndex = tokens.findIndex(
+    (candidate) => candidate.start === token.start && candidate.end === token.end
+  );
+  const owner = tokens[tokenIndex - 1]?.text === "." ? tokens[tokenIndex - 2] : void 0;
+  if (owner?.kind === "identifier" || owner?.kind === "type") {
+    const type2 = NEOSCRIPT_BUILTIN_TYPE_SYMBOLS.find(
+      (candidate) => candidate.name === owner.text
+    );
+    const symbol = type2?.members.find(
+      (candidate) => candidate.static === true && candidate.name === token.text
+    );
+    if (type2 && symbol) return { token, type: type2, symbol };
+  }
+  const type = NEOSCRIPT_BUILTIN_TYPE_SYMBOLS.find(
+    (candidate) => candidate.name === token.text
+  );
+  return type ? { token, type } : null;
+}
 function projectConstructionContractMarkdown(analysis, className) {
   const index = projectConstructionIndex(analysis);
   const contract = classConstructionContract(index, className);
@@ -29358,6 +29510,7 @@ var init_project_source_language_features = __esm({
     init_language_spec();
     init_project_source_semantics();
     init_project_source_variants();
+    init_project();
     init_project_source_semantics();
     init_project_source_settlement();
     init_project_source_tokens();
@@ -67143,6 +67296,7 @@ function isRuntimeFileValue(value) {
   return typeof fileId === "string" && fileId.length > 0;
 }
 function isRuntimeSpriteValue(value) {
+  if (isEmptySpriteValue(value)) return true;
   if (!isRuntimeFileValue(value)) return false;
   const sliceIndex = value.sliceIndex;
   return typeof sliceIndex === "number" && Number.isInteger(sliceIndex) && sliceIndex >= 0;
@@ -111261,7 +111415,7 @@ var init_registry2 = __esm({
     PROJECT_SCHEMA_CONTRACT = Object.freeze({
       formatVersion: 3,
       contractVersion: "3.13",
-      cliVersion: "0.31.7",
+      cliVersion: "0.31.9",
       projectFileUploadBatchSize: 32,
       documentRecords: {
         member: {
@@ -117856,7 +118010,7 @@ There is no --keep-current: preserving current semantic state defines flatten.
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.command === "--version") {
-    console.log("0.31.7");
+    console.log("0.31.9");
     return;
   }
   if (args.command === null || args.command === "help" || args.command === "--help" || args.command === "-h") {

package/package.json

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

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

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

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

@@ -49,8 +49,17 @@ if (player.Target != null) {
 return player.Target?.Name ?? "Unknown";
 ```
 
+Null propagation remains active across following required accesses in the same
+chain, so `config.Hat?.Head.Idle.Down.Frames` safely returns null when `Hat` is
+null. A descendant that is itself nullable still needs its own `?.`, `??`, `!`,
+or narrowing guard before the next access.
+
 Treat lookup-return values with the same nullable narrowing rules.
 
+Use `SpriteInfo.Empty` when a required sprite should intentionally render no
+image. It is the canonical non-null empty sprite: it has no backing file and
+uses slice index zero.
+
 Let runtime ownership—not body kind—decide whether a write target is Immutable,
 Save, Session, Setter, or otherwise writable. A constructor writes only its
 `this` instance. A writable structured-leaf field still inherits the receiver's