@neocompose/cli 0.31.17 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.32.0] - 2026-08-18
+
+### Added
+
+- P69 Math builtins: call `Math.Min`, `Max`, `Clamp`, `Round`, `Floor`,
+  `Ceiling`, `Truncate`, `Abs`, `Sign`, and `Sqrt`, and read the `Math.PI` and
+  `Math.E` constants, from any NeoScript body. Results are inferred from the
+  argument types under the arithmetic join rule, `Round`/`Floor`/`Ceiling`/
+  `Truncate` return `int` on `int` and `float` input, and `Math` is now a
+  reserved name.
+
 ## [0.31.17] - 2026-08-18
 
 ### Fixed

package/dist/neo.mjs

@@ -1308,6 +1308,20 @@ function structuredLeafFieldProperties(owner) {
     (field) => property(owner, field.name, field.type, field.documentation, true)
   );
 }
+function mathFunction(name, parameterNames, documentation, returnType = FLOAT_TYPE) {
+  return {
+    id: `${NEOSCRIPT_MATH_TYPE_ID}:function:${name}`,
+    name,
+    kind: "function",
+    type: returnType,
+    returnType,
+    parameters: parameterNames.map(
+      (parameterName) => parameter(parameterName, FLOAT_TYPE)
+    ),
+    documentation,
+    static: true
+  };
+}
 function vectorTypes() {
   const names = [
     "Vector2",
@@ -1322,7 +1336,7 @@ function vectorTypes() {
     members: structuredLeafFieldProperties(name)
   }));
 }
-var NEO_PROJECT_IGNORED_DIRECTORY_NAMES, NEOSCRIPT_KEYWORDS, NEOSCRIPT_INFERRED_LOCAL_KEYWORD, NEOSCRIPT_CONSTRUCTOR_KEYWORD, NEOSCRIPT_PRIMITIVE_TYPES, NEOSCRIPT_BUILTIN_TYPES, NEO_VARIANT_TYPE_NAME, NEO_VARIANT_FOLDER_TYPE_NAME, NEO_LOOKUP_VARIANT_TYPE_NAME, NEO_LOOKUP_VARIANT_FOLDER_TYPE_NAME, NEO_VARIANT_SCOPE_NAME, NEO_VARIANT_RESERVED_NAME, NEO_VARIANT_FOLDER_PATH_SEPARATOR, 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 NEO_PROJECT_IGNORED_DIRECTORY_NAMES, NEOSCRIPT_KEYWORDS, NEOSCRIPT_INFERRED_LOCAL_KEYWORD, NEOSCRIPT_CONSTRUCTOR_KEYWORD, NEOSCRIPT_PRIMITIVE_TYPES, NEOSCRIPT_BUILTIN_ANNOTATION_TYPES, NEOSCRIPT_BUILTIN_NAMESPACES, NEOSCRIPT_BUILTIN_TYPES, NEO_VARIANT_TYPE_NAME, NEO_VARIANT_FOLDER_TYPE_NAME, NEO_LOOKUP_VARIANT_TYPE_NAME, NEO_LOOKUP_VARIANT_FOLDER_TYPE_NAME, NEO_VARIANT_SCOPE_NAME, NEO_VARIANT_RESERVED_NAME, NEO_VARIANT_FOLDER_PATH_SEPARATOR, 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_MATH_TYPE_ID, MATH_INFERENCE_RULE, MATH_INTEGRAL_RULE, NEOSCRIPT_BUILTIN_TYPE_SYMBOLS;
 var init_language_spec = __esm({
   "../packages/neoscript-language/src/language-spec.ts"() {
     "use strict";
@@ -1384,7 +1398,7 @@ var init_language_spec = __esm({
       "bool",
       "string"
     ];
-    NEOSCRIPT_BUILTIN_TYPES = [
+    NEOSCRIPT_BUILTIN_ANNOTATION_TYPES = [
       "Dictionary",
       "List",
       "Set",
@@ -1410,6 +1424,11 @@ var init_language_spec = __esm({
       "Vector3Int",
       "Color"
     ];
+    NEOSCRIPT_BUILTIN_NAMESPACES = ["Math"];
+    NEOSCRIPT_BUILTIN_TYPES = [
+      ...NEOSCRIPT_BUILTIN_ANNOTATION_TYPES,
+      ...NEOSCRIPT_BUILTIN_NAMESPACES
+    ];
     NEO_VARIANT_TYPE_NAME = "NeoVariant";
     NEO_VARIANT_FOLDER_TYPE_NAME = "NeoVariantFolder";
     NEO_LOOKUP_VARIANT_TYPE_NAME = "NeoLookupVariant";
@@ -1658,6 +1677,9 @@ var init_language_spec = __esm({
       fileId: "",
       sliceIndex: 0
     });
+    NEOSCRIPT_MATH_TYPE_ID = "builtin:Math";
+    MATH_INFERENCE_RULE = "Accepts int, float, or decimal; the result mirrors the widest argument type.";
+    MATH_INTEGRAL_RULE = "Accepts int, float, or decimal; int and float return int, decimal returns decimal.";
     NEOSCRIPT_BUILTIN_TYPE_SYMBOLS = [
       {
         id: "builtin:SpriteInfo",
@@ -1730,6 +1752,87 @@ var init_language_spec = __esm({
         name: "Color",
         kind: "builtin",
         members: structuredLeafFieldProperties("Color")
+      },
+      {
+        id: NEOSCRIPT_MATH_TYPE_ID,
+        name: "Math",
+        kind: "builtin",
+        documentation: "Numeric builtins with C# names and C# semantics. Math is a qualifier only \u2014 it names no type and holds no value, and every member is a pure function or constant.",
+        members: [
+          mathFunction(
+            "Min",
+            ["a", "b"],
+            `Returns the smaller of two values. ${MATH_INFERENCE_RULE} Ties return the first argument.`
+          ),
+          mathFunction(
+            "Max",
+            ["a", "b"],
+            `Returns the larger of two values. ${MATH_INFERENCE_RULE} Ties return the first argument.`
+          ),
+          mathFunction(
+            "Clamp",
+            ["value", "min", "max"],
+            `Returns value pinned to the inclusive range min..max. ${MATH_INFERENCE_RULE} Requires min <= max.`
+          ),
+          mathFunction(
+            "Round",
+            ["x"],
+            `Rounds to the nearest integer; midpoints round to even (banker's rounding). ${MATH_INTEGRAL_RULE}`,
+            INT_TYPE
+          ),
+          mathFunction(
+            "Floor",
+            ["x"],
+            `Rounds toward negative infinity. ${MATH_INTEGRAL_RULE}`,
+            INT_TYPE
+          ),
+          mathFunction(
+            "Ceiling",
+            ["x"],
+            `Rounds toward positive infinity. ${MATH_INTEGRAL_RULE}`,
+            INT_TYPE
+          ),
+          mathFunction(
+            "Truncate",
+            ["x"],
+            `Rounds toward zero. ${MATH_INTEGRAL_RULE}`,
+            INT_TYPE
+          ),
+          mathFunction(
+            "Abs",
+            ["x"],
+            `Returns the absolute value. ${MATH_INFERENCE_RULE}`
+          ),
+          mathFunction(
+            "Sign",
+            ["x"],
+            "Returns -1, 0, or 1 for a negative, zero, or positive value. Accepts int, float, or decimal and always returns int.",
+            INT_TYPE
+          ),
+          mathFunction(
+            "Sqrt",
+            ["x"],
+            "Returns the square root. Accepts int or float and returns float; does not accept decimal."
+          ),
+          {
+            ...property(
+              "Math",
+              "PI",
+              FLOAT_TYPE,
+              "The ratio of a circle's circumference to its diameter (3.141592653589793)."
+            ),
+            static: true
+          },
+          {
+            ...property(
+              "Math",
+              "E",
+              FLOAT_TYPE,
+              "The base of the natural logarithm (2.718281828459045)."
+            ),
+            static: true
+          }
+        ]
       }
     ];
   }
@@ -2320,12 +2423,11 @@ function complete(snapshot, position) {
         word
       );
     } else {
-      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);
+      candidates = completionItemsForResolution(
+        snapshot,
+        resolveChain(snapshot, receiverTokens, offset),
+        word
+      );
     }
   } else if (tail?.kind === "identifier" && tail.text === NEOSCRIPT_CONSTRUCTOR_KEYWORD) {
     candidates = constructorCompletionItems(
@@ -3205,6 +3307,7 @@ function typeCompletionItems(snapshot, word) {
     )
   );
   for (const type of snapshot.project.typeByName.values()) {
+    if (type.id === NEOSCRIPT_MATH_TYPE_ID) continue;
     items.push(typeCompletion(type, word, snapshot));
   }
   return items;
@@ -3409,9 +3512,16 @@ function switchCaseEnumContext(snapshot, offset) {
 function resolveChain(snapshot, tokens, offset) {
   if (tokens.length === 0) return null;
   const constructorType = tokens[0]?.kind === "identifier" && tokens[0].text === NEOSCRIPT_CONSTRUCTOR_KEYWORD && tokens[1]?.kind === "identifier" ? snapshot.project.typeByName.get(tokens[1].text) : void 0;
+  const staticRoot = tokens[0]?.kind === "type" ? snapshot.project.typeByName.get(tokens[0].text) : void 0;
   let current;
   let cursor;
-  if (constructorType?.constructorSignature) {
+  if (staticRoot) {
+    current = {
+      type: { kind: "named", typeId: staticRoot.id },
+      staticType: staticRoot
+    };
+    cursor = 1;
+  } else if (constructorType?.constructorSignature) {
     current = { type: constructorType.constructorSignature.returnType };
     const open = tokens.findIndex(
       (token, index) => index >= 2 && token.kind === "punctuation" && token.text === "("
@@ -4509,6 +4619,7 @@ var init_analyzer = __esm({
     RESERVED_NAMES = /* @__PURE__ */ new Set([
       ...NEOSCRIPT_KEYWORDS,
       ...NEOSCRIPT_PRIMITIVE_TYPES,
+      ...NEOSCRIPT_BUILTIN_NAMESPACES,
       "Dictionary",
       "Set"
     ]);
@@ -8867,6 +8978,30 @@ function numericResult(left, right) {
   }
   return { kind: "primitive", name: "int" };
 }
+function isContextualNumericLiteral(expression) {
+  if (expression.kind === "litInt" || expression.kind === "litFloat") {
+    return true;
+  }
+  return expression.kind === "unary" && expression.op === "-" && (expression.operand.kind === "litInt" || expression.operand.kind === "litFloat");
+}
+function mathResultType(rule, joined, pos) {
+  switch (rule) {
+    case "join":
+      return joined;
+    case "integral":
+      return isPrimitive(joined, "decimal") ? joined : { kind: "primitive", name: "int" };
+    case "int":
+      return { kind: "primitive", name: "int" };
+    case "float":
+      if (isPrimitive(joined, "decimal")) {
+        throw new CompileError(
+          "Math.Sqrt does not accept decimal; convert explicitly with value.ToFloat().",
+          pos
+        );
+      }
+      return { kind: "primitive", name: "float" };
+  }
+}
 function normalizedReturnType(type, kind) {
   if (kind === "action" || kind === "setter" || kind === "constructor") {
     return { kind: "primitive", name: "null" };
@@ -9209,7 +9344,7 @@ function switchValueKey(value) {
   const enumId = value.typeInfo.type === 8 /* Enum */ ? value.typeInfo.enumId : null;
   return JSON.stringify([value.typeInfo.type, enumId, value.value]);
 }
-var CONSTRUCTING_FUNCTION_KINDS, VARIANT_INITIALIZE_NAME, VARIANT_APPLY_NAME, WRITE_TARGET_DESCRIPTIONS, FALLTHROUGH_LABELS, Scope, StrictNeoScriptResolver, SPRITE_DERIVED_MEMBERS;
+var CONSTRUCTING_FUNCTION_KINDS, VARIANT_INITIALIZE_NAME, VARIANT_APPLY_NAME, MATH_NAMESPACE_NAME, MATH_FUNCTIONS, MATH_CONSTANTS, WRITE_TARGET_DESCRIPTIONS, FALLTHROUGH_LABELS, Scope, StrictNeoScriptResolver, SPRITE_DERIVED_MEMBERS;
 var init_strict_resolver = __esm({
   "../packages/neoscript-language/src/strict-resolver.ts"() {
     "use strict";
@@ -9233,6 +9368,23 @@ var init_strict_resolver = __esm({
     );
     VARIANT_INITIALIZE_NAME = "Initialize";
     VARIANT_APPLY_NAME = "ToVariant";
+    MATH_NAMESPACE_NAME = "Math";
+    MATH_FUNCTIONS = /* @__PURE__ */ new Map([
+      ["Min", { op: "min", arity: 2, result: "join" }],
+      ["Max", { op: "max", arity: 2, result: "join" }],
+      ["Clamp", { op: "clamp", arity: 3, result: "join" }],
+      ["Round", { op: "round", arity: 1, result: "integral" }],
+      ["Floor", { op: "floor", arity: 1, result: "integral" }],
+      ["Ceiling", { op: "ceiling", arity: 1, result: "integral" }],
+      ["Truncate", { op: "truncate", arity: 1, result: "integral" }],
+      ["Abs", { op: "abs", arity: 1, result: "join" }],
+      ["Sign", { op: "sign", arity: 1, result: "int" }],
+      ["Sqrt", { op: "sqrt", arity: 1, result: "float" }]
+    ]);
+    MATH_CONSTANTS = /* @__PURE__ */ new Map([
+      ["PI", 3.141592653589793],
+      ["E", 2.718281828459045]
+    ]);
     WRITE_TARGET_DESCRIPTIONS = {
       this: "`this`",
       local: "a local",
@@ -10230,6 +10382,12 @@ var init_strict_resolver = __esm({
         };
       }
       assertLocalNameAvailable(name, scope, pos) {
+        if (name === MATH_NAMESPACE_NAME) {
+          throw new CompileError(
+            `Cannot declare a local named '${MATH_NAMESPACE_NAME}' because it is a builtin namespace.`,
+            pos
+          );
+        }
         if (!scope.lookup(name)) return;
         throw new CompileError(
           `Cannot declare local '${name}' because that name is already used in an enclosing or current scope.`,
@@ -11447,6 +11605,12 @@ var init_strict_resolver = __esm({
             false
           );
         }
+        if (name === MATH_NAMESPACE_NAME) {
+          throw new CompileError(
+            `'${MATH_NAMESPACE_NAME}' is a builtin namespace, not a value.`,
+            pos
+          );
+        }
         const type = this.project.typeByName.get(name);
         if (type?.kind === "enum") {
           return {
@@ -11844,6 +12008,15 @@ var init_strict_resolver = __esm({
               { ...NEOSCRIPT_SPRITE_INFO_EMPTY_VALUE }
             );
           }
+          if (receiverAst.name === MATH_NAMESPACE_NAME) {
+            if (optional) {
+              throw new CompileError(
+                `Optional chaining is not valid on builtin namespace '${MATH_NAMESPACE_NAME}'.`,
+                pos
+              );
+            }
+            return this.resolveMathMemberRead(name, pos);
+          }
           const staticType = this.project.typeByName.get(receiverAst.name);
           if (staticType && staticType.kind !== "enum") {
             if (optional) {
@@ -12365,6 +12538,114 @@ var init_strict_resolver = __esm({
           );
         }
       }
+      /**
+       * P69 §2.7. A member read on the `Math` namespace: the two constants lower
+       * to `float` literals, and nothing else on `Math` is readable as a value.
+       */
+      resolveMathMemberRead(name, pos) {
+        const constant = MATH_CONSTANTS.get(name);
+        if (constant !== void 0) {
+          return literal({ kind: "primitive", name: "float" }, constant);
+        }
+        if (MATH_FUNCTIONS.has(name)) {
+          throw new CompileError(
+            `Math function '${MATH_NAMESPACE_NAME}.${name}' must be called with \`()\`; it cannot be read as a value.`,
+            pos
+          );
+        }
+        throw new CompileError(
+          `${MATH_NAMESPACE_NAME} has no function '${name}'.`,
+          pos
+        );
+      }
+      /**
+       * P69 §2. A call on the `Math` namespace. Every function is one symbol
+       * whose result type is computed here from the resolved argument types —
+       * the arithmetic operator join rule, verbatim — and lowers to a `mathOp`
+       * intrinsic carrying the operands in declaration order.
+       */
+      resolveMathCall(name, args, scope, pos) {
+        const fn = MATH_FUNCTIONS.get(name);
+        if (!fn) {
+          if (MATH_CONSTANTS.has(name)) {
+            throw new CompileError(
+              `${MATH_NAMESPACE_NAME}.${name} is a constant, not a function; read it without \`()\`.`,
+              pos
+            );
+          }
+          throw new CompileError(
+            `${MATH_NAMESPACE_NAME} has no function '${name}'.`,
+            pos
+          );
+        }
+        const label = `${MATH_NAMESPACE_NAME}.${name}`;
+        requireArgCount(label, args, fn.arity, pos);
+        const resolved = args.map((argument2, index) => {
+          const value = this.resolveExpression(argument2, scope);
+          if (isNullable(value.type)) {
+            throw new CompileError(
+              `${label} requires non-optional arguments; got ${this.describe(value.type)} for argument ${index + 1}.`,
+              argument2.pos
+            );
+          }
+          if (!isNumeric(value.type)) {
+            throw new CompileError(
+              `${label} requires numeric arguments; got ${this.describe(value.type)} for argument ${index + 1}.`,
+              argument2.pos
+            );
+          }
+          return value;
+        });
+        const joined = this.joinMathArguments(args, resolved, scope, pos);
+        return intrinsic(
+          "mathOp" /* MathOp */,
+          {
+            op: fn.op,
+            argPointers: joined.arguments.map((argument2) => argument2.pointer),
+            ...isPrimitive(joined.type, "decimal") ? { decimal: true } : {}
+          },
+          mathResultType(fn.result, joined.type, pos)
+        );
+      }
+      /**
+       * P69 §2.1. The join of a `Math` call's argument types, after the second
+       * resolution pass that gives numeric literals beside a `decimal` argument
+       * their decimal reading.
+       *
+       * A call's argument list carries no declared expected type once typing is
+       * inferred, so `Math.Max(price, 0.99)` would otherwise type `0.99` as
+       * `float` and die on the mix rule with no decimal literal suffix to escape
+       * with. Re-resolving from the preserved raw lexeme is the assignment-context
+       * rule applied across the argument list, not a new coercion: a non-literal
+       * `float` expression still refuses to mix.
+       */
+      joinMathArguments(args, resolved, scope, pos) {
+        const decimalType = {
+          kind: "primitive",
+          name: "decimal"
+        };
+        const anyDecimal = resolved.some(
+          (argument2) => isPrimitive(argument2.type, "decimal")
+        );
+        const settled = !anyDecimal ? resolved : resolved.map((argument2, index) => {
+          const ast = requiredAt(args, index);
+          if (!isContextualNumericLiteral(ast)) return argument2;
+          return this.resolveExpression(ast, scope, decimalType);
+        });
+        if (anyDecimal && settled.some((argument2) => isPrimitive(argument2.type, "float"))) {
+          throw new CompileError(
+            "Decimal and Float cannot be mixed implicitly; convert explicitly with value.ToDecimal(digits) or value.ToFloat().",
+            pos
+          );
+        }
+        return {
+          arguments: settled,
+          type: settled.reduce(
+            (left, right) => numericResult(left, right.type),
+            { kind: "primitive", name: "int" }
+          )
+        };
+      }
       resolveCall(callee, argumentsList2, scope, pos) {
         const variantCall = this.resolveVariantCall(
           callee,
@@ -12458,6 +12739,15 @@ var init_strict_resolver = __esm({
           );
         }
         if (callee.receiver.kind === "ident" && !scope.lookup(callee.receiver.name)) {
+          if (callee.receiver.name === MATH_NAMESPACE_NAME) {
+            if (callee.optional) {
+              throw new CompileError(
+                `Optional chaining is not valid on builtin namespace '${MATH_NAMESPACE_NAME}'.`,
+                pos
+              );
+            }
+            return this.resolveMathCall(callee.name, argumentsList2, scope, pos);
+          }
           const staticType = this.project.typeByName.get(callee.receiver.name);
           if (staticType && staticType.kind !== "enum") {
             if (callee.optional) {
@@ -14318,6 +14608,12 @@ var init_strict_resolver = __esm({
             resolved = { kind: "primitive", name: type.name };
             break;
           case "named": {
+            if (type.name === MATH_NAMESPACE_NAME) {
+              throw new CompileError(
+                `'${MATH_NAMESPACE_NAME}' is a builtin namespace, not a type.`,
+                type.pos
+              );
+            }
             const builtin = namedPrimitive(type.name);
             if (builtin) {
               resolved = { kind: "primitive", name: builtin };
@@ -26195,7 +26491,7 @@ var init_project_source_type_checker = __esm({
     ]);
     BUILTIN_TYPES = /* @__PURE__ */ new Set([
       ...NEOSCRIPT_PRIMITIVE_TYPES,
-      ...NEOSCRIPT_BUILTIN_TYPES,
+      ...NEOSCRIPT_BUILTIN_ANNOTATION_TYPES,
       "void",
       "null",
       "Project",
@@ -26213,7 +26509,10 @@ var init_project_source_type_checker = __esm({
       "NeoAudioClip",
       "ProjectRelation"
     ]);
-    RESERVED_NAMES2 = new Set(NEOSCRIPT_KEYWORDS);
+    RESERVED_NAMES2 = /* @__PURE__ */ new Set([
+      ...NEOSCRIPT_KEYWORDS,
+      ...NEOSCRIPT_BUILTIN_NAMESPACES
+    ]);
   }
 });
 
@@ -27116,7 +27415,7 @@ var init_project_source_analysis = __esm({
     init_project_source_parameter_defaults();
     BUILTIN_TYPE_NAMES = /* @__PURE__ */ new Set([
       ...NEOSCRIPT_PRIMITIVE_TYPES,
-      ...NEOSCRIPT_BUILTIN_TYPES,
+      ...NEOSCRIPT_BUILTIN_ANNOTATION_TYPES,
       "void",
       "null",
       "Project",
@@ -27134,7 +27433,10 @@ var init_project_source_analysis = __esm({
       "NeoAudioClip",
       "ProjectRelation"
     ]);
-    RESERVED_NAMES3 = new Set(NEOSCRIPT_KEYWORDS);
+    RESERVED_NAMES3 = /* @__PURE__ */ new Set([
+      ...NEOSCRIPT_KEYWORDS,
+      ...NEOSCRIPT_BUILTIN_NAMESPACES
+    ]);
     SYSTEM_RECORD_ID_PREFIX = "system_";
     RFC_4122_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
     QUARANTINED_LEGACY_SYSTEM_ID_PREFIXES = [
@@ -27634,7 +27936,7 @@ function projectFallbackCompletions(analysis, document, position) {
   }
   for (const typeName of [
     ...NEOSCRIPT_PRIMITIVE_TYPES,
-    ...NEOSCRIPT_BUILTIN_TYPES
+    ...NEOSCRIPT_BUILTIN_ANNOTATION_TYPES
   ]) {
     if (expression) continue;
     items.set(typeName, {
@@ -41565,6 +41867,18 @@ function isNSFunctionDecimalOp(value) {
   const digits = info.digitsPointer;
   return digits === void 0 || isNSPointer(digits);
 }
+function isNSFunctionMathOp(value) {
+  const v = value;
+  if (v?.type !== "mathOp" /* mathOp */) return false;
+  const info = v.info;
+  if (typeof info !== "object" || info === null) return false;
+  if (!NS_MATH_OPS.includes(info.op)) return false;
+  const args = info.argPointers;
+  if (!Array.isArray(args)) return false;
+  if (!args.every(isNSPointer)) return false;
+  const decimal2 = info.decimal;
+  return decimal2 === void 0 || decimal2 === true;
+}
 function isNSFunctionCount(value) {
   const v = value;
   if (v?.type !== "count" /* count */) return false;
@@ -41612,7 +41926,7 @@ function isNSFunction(value) {
   return isNSFunctionClassConstructor(value) || isNSFunctionClassClone(value) || isNSFunctionListIndex(value) || isNSFunctionSelect(value) || isNSFunctionFirst(value) || isNSFunctionFirstOrDefault(value) || isNSFunctionWhere(value) || isNSFunctionContains(value) || // stringOp was missing from this chain since its introduction — a
   // compiled getter using ToLower()/StartsWith() would fail pointer
   // validation anywhere isNSFunction gates. Fixed alongside decimalOp.
-  isNSFunctionStringOp(value) || isNSFunctionDecimalOp(value) || isNSFunctionCount(value) || isNSFunctionVisitCount(value) || isNSFunctionHasVisited(value) || isNSFunctionVectorConstructor(value) || isNSFunctionImageSlice(value) || isNSFunctionVariantInitialize(value) || isNSFunctionVariantApply(value) || isNSFunctionDeclaredConstructor(value);
+  isNSFunctionStringOp(value) || isNSFunctionDecimalOp(value) || isNSFunctionMathOp(value) || isNSFunctionCount(value) || isNSFunctionVisitCount(value) || isNSFunctionHasVisited(value) || isNSFunctionVectorConstructor(value) || isNSFunctionImageSlice(value) || isNSFunctionVariantInitialize(value) || isNSFunctionVariantApply(value) || isNSFunctionDeclaredConstructor(value);
 }
 function isNSInstructionVariable(value) {
   const v = value;
@@ -41903,7 +42217,7 @@ function isNSVoidBody(value) {
   if (value.typeInfo.type !== 0 /* Null */) return false;
   return value.typeInfo.required === true;
 }
-var NS_STRING_OPS, NS_DECIMAL_OPS;
+var NS_STRING_OPS, NS_DECIMAL_OPS, NS_MATH_OPS;
 var init_neoscript_guards = __esm({
   "../src/models/neoscript/neoscript-guards.ts"() {
     "use strict";
@@ -41924,6 +42238,18 @@ var init_neoscript_guards = __esm({
       "toFloat",
       "toDecimal"
     ];
+    NS_MATH_OPS = [
+      "min",
+      "max",
+      "clamp",
+      "round",
+      "floor",
+      "ceiling",
+      "truncate",
+      "abs",
+      "sign",
+      "sqrt"
+    ];
   }
 });
 
@@ -63087,6 +63413,25 @@ function compareDecimalStrings(a, b) {
   if (aligned.a > aligned.b) return 1;
   return 0;
 }
+function minDecimalStrings(a, b) {
+  return compareDecimalStrings(a, b) <= 0 ? a : b;
+}
+function maxDecimalStrings(a, b) {
+  return compareDecimalStrings(a, b) >= 0 ? a : b;
+}
+function clampDecimalStrings(value, min, max) {
+  if (compareDecimalStrings(min, max) > 0) {
+    throw new DecimalClampRangeError(MATH_CLAMP_RANGE_MESSAGE);
+  }
+  if (compareDecimalStrings(value, min) < 0) return min;
+  if (compareDecimalStrings(value, max) > 0) return max;
+  return value;
+}
+function absDecimalString(value) {
+  const parts = parseDecimalArg(value, "value");
+  const magnitude = parts.coefficient < 0n ? -parts.coefficient : parts.coefficient;
+  return formatDecimalParts({ coefficient: magnitude, scale: parts.scale });
+}
 function addDecimalStrings(a, b) {
   const aligned = alignScales(parseDecimalArg(a, "a"), parseDecimalArg(b, "b"));
   return formatDecimalParts(
@@ -63149,6 +63494,32 @@ function roundDecimalString(value, digits) {
   const rounded = roundParts(parseDecimalArg(value, "value"), digits);
   return formatDecimalParts(assertWithinEnvelope(rounded, "round"));
 }
+function toIntegralParts(parts, direction) {
+  if (parts.scale === 0) return parts;
+  const divisor = pow10(parts.scale);
+  const quotient = parts.coefficient / divisor;
+  const remainder = parts.coefficient % divisor;
+  if (remainder === 0n) return { coefficient: quotient, scale: 0 };
+  if (direction === "floor" && remainder < 0n) {
+    return { coefficient: quotient - 1n, scale: 0 };
+  }
+  if (direction === "ceiling" && remainder > 0n) {
+    return { coefficient: quotient + 1n, scale: 0 };
+  }
+  return { coefficient: quotient, scale: 0 };
+}
+function floorDecimalString(value) {
+  const parts = toIntegralParts(parseDecimalArg(value, "value"), "floor");
+  return formatDecimalParts(assertWithinEnvelope(parts, "floor"));
+}
+function ceilingDecimalString(value) {
+  const parts = toIntegralParts(parseDecimalArg(value, "value"), "ceiling");
+  return formatDecimalParts(assertWithinEnvelope(parts, "ceiling"));
+}
+function truncateDecimalString(value) {
+  const parts = toIntegralParts(parseDecimalArg(value, "value"), "truncate");
+  return formatDecimalParts(assertWithinEnvelope(parts, "truncate"));
+}
 function divideDecimalStrings(a, b, digits) {
   assertDigitsInRange(digits, "divide");
   const dividend = parseDecimalArg(a, "a");
@@ -63229,7 +63600,7 @@ function floatFromDecimalString(value) {
   assertCanonicalInput(value, "value");
   return Number(value);
 }
-var DecimalOverflowError, DecimalDivisionByZeroError, DecimalDigitsRangeError, DecimalNonFiniteError, TEN;
+var DecimalOverflowError, DecimalDivisionByZeroError, DecimalDigitsRangeError, DecimalNonFiniteError, DecimalClampRangeError, MATH_CLAMP_RANGE_MESSAGE, TEN;
 var init_decimal_math = __esm({
   "../src/models/decimal/decimal-math.ts"() {
     "use strict";
@@ -63242,6 +63613,9 @@ var init_decimal_math = __esm({
     };
     DecimalNonFiniteError = class extends Error {
     };
+    DecimalClampRangeError = class extends Error {
+    };
+    MATH_CLAMP_RANGE_MESSAGE = "Math.Clamp requires min <= max.";
     TEN = 10n;
   }
 });
@@ -68130,7 +68504,7 @@ function coerceDecimalOperand(value, context) {
   );
 }
 function rethrowDecimalError(error) {
-  if (error instanceof DecimalOverflowError || error instanceof DecimalDivisionByZeroError || error instanceof DecimalDigitsRangeError || error instanceof DecimalNonFiniteError) {
+  if (error instanceof DecimalOverflowError || error instanceof DecimalDivisionByZeroError || error instanceof DecimalDigitsRangeError || error instanceof DecimalNonFiniteError || error instanceof DecimalClampRangeError) {
     throw new NSGetterRuntimeError(error.message);
   }
   throw error;
@@ -68157,6 +68531,163 @@ function applyDecimalArithmetic(op, operands) {
     rethrowDecimalError(error);
   }
 }
+function mathArgPointer(info, index, fn) {
+  const pointer = info.argPointers[index];
+  if (pointer === void 0) {
+    throw new NSGetterRuntimeError(
+      `Math.${fn} is missing argument ${index + 1}.`
+    );
+  }
+  return pointer;
+}
+function mathNumberArg(value, fn) {
+  if (value === null || value === void 0) {
+    throw new NSGetterRuntimeError(`Math.${fn} argument is null.`);
+  }
+  if (typeof value !== "number") {
+    throw new NSGetterRuntimeError(
+      `Math.${fn} argument is not numeric: ${typeof value}.`
+    );
+  }
+  return value;
+}
+function mathDecimalArg(value, fn) {
+  if (value === null || value === void 0) {
+    throw new NSGetterRuntimeError(`Math.${fn} argument is null.`);
+  }
+  if (typeof value !== "string" && typeof value !== "number") {
+    throw new NSGetterRuntimeError(
+      `Math.${fn} argument is not numeric: ${typeof value}.`
+    );
+  }
+  return coerceDecimalOperand(value, `Math.${fn}`);
+}
+function requireFiniteMathArg(value, fn) {
+  if (!Number.isFinite(value)) {
+    throw new NSGetterRuntimeError(`Math.${fn} requires a finite argument.`);
+  }
+  return value;
+}
+function roundHalfEven(value) {
+  if (Math.abs(value) >= DOUBLE_INTEGRAL_MAGNITUDE) return value;
+  const integral = Math.floor(value);
+  const fraction = value - integral;
+  if (fraction > 0.5) return integral + 1;
+  if (fraction < 0.5) return integral;
+  if (integral % 2 === 0) return integral;
+  return integral + 1;
+}
+function evalMathOp(info, scope, ctx) {
+  const fn = NS_MATH_OP_NAMES[info.op];
+  if (info.decimal === true) return evalDecimalMathOp(info, fn, scope, ctx);
+  const value = mathNumberArg(
+    evalPointer(mathArgPointer(info, 0, fn), scope, ctx),
+    fn
+  );
+  switch (info.op) {
+    case "min":
+      return Math.min(
+        value,
+        mathNumberArg(evalPointer(mathArgPointer(info, 1, fn), scope, ctx), fn)
+      );
+    case "max":
+      return Math.max(
+        value,
+        mathNumberArg(evalPointer(mathArgPointer(info, 1, fn), scope, ctx), fn)
+      );
+    case "clamp": {
+      const min = mathNumberArg(
+        evalPointer(mathArgPointer(info, 1, fn), scope, ctx),
+        fn
+      );
+      const max = mathNumberArg(
+        evalPointer(mathArgPointer(info, 2, fn), scope, ctx),
+        fn
+      );
+      if (min > max) {
+        throw new NSGetterRuntimeError(MATH_CLAMP_RANGE_MESSAGE);
+      }
+      if (value < min) return min;
+      if (value > max) return max;
+      return value;
+    }
+    case "round":
+      return roundHalfEven(requireFiniteMathArg(value, fn));
+    case "floor":
+      return Math.floor(requireFiniteMathArg(value, fn));
+    case "ceiling":
+      return Math.ceil(requireFiniteMathArg(value, fn));
+    case "truncate":
+      return Math.trunc(requireFiniteMathArg(value, fn));
+    case "abs":
+      return Math.abs(value);
+    case "sign":
+      if (Number.isNaN(value)) {
+        throw new NSGetterRuntimeError("Math.Sign is undefined for NaN.");
+      }
+      if (value > 0) return 1;
+      if (value < 0) return -1;
+      return 0;
+    case "sqrt":
+      return Math.sqrt(value);
+  }
+}
+function evalDecimalMathOp(info, fn, scope, ctx) {
+  const value = mathDecimalArg(
+    evalPointer(mathArgPointer(info, 0, fn), scope, ctx),
+    fn
+  );
+  try {
+    switch (info.op) {
+      case "min":
+        return minDecimalStrings(
+          value,
+          mathDecimalArg(
+            evalPointer(mathArgPointer(info, 1, fn), scope, ctx),
+            fn
+          )
+        );
+      case "max":
+        return maxDecimalStrings(
+          value,
+          mathDecimalArg(
+            evalPointer(mathArgPointer(info, 1, fn), scope, ctx),
+            fn
+          )
+        );
+      case "clamp":
+        return clampDecimalStrings(
+          value,
+          mathDecimalArg(
+            evalPointer(mathArgPointer(info, 1, fn), scope, ctx),
+            fn
+          ),
+          mathDecimalArg(
+            evalPointer(mathArgPointer(info, 2, fn), scope, ctx),
+            fn
+          )
+        );
+      case "round":
+        return roundDecimalString(value, 0);
+      case "floor":
+        return floorDecimalString(value);
+      case "ceiling":
+        return ceilingDecimalString(value);
+      case "truncate":
+        return truncateDecimalString(value);
+      case "abs":
+        return absDecimalString(value);
+      case "sign":
+        return compareDecimalStrings(value, "0");
+      case "sqrt":
+        throw new NSGetterRuntimeError(
+          "Math.Sqrt does not accept decimal arguments."
+        );
+    }
+  } catch (error) {
+    rethrowDecimalError(error);
+  }
+}
 function stringifyForInterp(v) {
   if (v === null || v === void 0) return "";
   if (typeof v === "string") return v;
@@ -68676,6 +69207,8 @@ function evalFunction(fn, scope, ctx) {
       }
       break;
     }
+    case "mathOp" /* mathOp */:
+      return evalMathOp(fn.info, scope, ctx);
     case "stringOp" /* stringOp */: {
       const receiver = evalPointer(fn.info.receiverPointer, scope, ctx);
       if (typeof receiver !== "string") {
@@ -71888,7 +72421,7 @@ function iterateCollection(c, ctx, callback) {
     return callback(entry, key, valueId);
   });
 }
-var DELEGATE_LEXICAL_THIS, DELEGATE_LEXICAL_ROOT, NonCatchableNSGetterRuntimeError, NativeFunctionDelegateUnavailableError, CorruptNeoScriptIRError, NeoScriptResourceLimitError, NeoScriptWallClockTimeoutError, DEFAULT_NEO_SCRIPT_EXECUTION_BUDGET_LIMITS, liveListIndexesByProject, evaluatorOwnershipCachesByBase, MAX_CONSTRUCTION_DEPTH, MAX_LOOP_ITERATIONS, resolutionCacheByMembers, NO_SCHEMA_REVISION, LazyValueOverlay, READONLY_FOREACH_BINDING_ERROR, READONLY_CATCH_BINDING_ERROR, EMPTY_SUPPLIED_CONSTRUCTOR_FIELDS;
+var DELEGATE_LEXICAL_THIS, DELEGATE_LEXICAL_ROOT, NonCatchableNSGetterRuntimeError, NativeFunctionDelegateUnavailableError, CorruptNeoScriptIRError, NeoScriptResourceLimitError, NeoScriptWallClockTimeoutError, DEFAULT_NEO_SCRIPT_EXECUTION_BUDGET_LIMITS, liveListIndexesByProject, evaluatorOwnershipCachesByBase, MAX_CONSTRUCTION_DEPTH, MAX_LOOP_ITERATIONS, resolutionCacheByMembers, NO_SCHEMA_REVISION, LazyValueOverlay, READONLY_FOREACH_BINDING_ERROR, READONLY_CATCH_BINDING_ERROR, NS_MATH_OP_NAMES, DOUBLE_INTEGRAL_MAGNITUDE, EMPTY_SUPPLIED_CONSTRUCTOR_FIELDS;
 var init_evaluateNSGetter = __esm({
   "../src/view-models/neoscript-evaluator/evaluateNSGetter.ts"() {
     "use strict";
@@ -72032,6 +72565,19 @@ var init_evaluateNSGetter = __esm({
     };
     READONLY_FOREACH_BINDING_ERROR = "Cannot assign to a read-only foreach iterator binding.";
     READONLY_CATCH_BINDING_ERROR = "Cannot assign to a read-only catch message binding.";
+    NS_MATH_OP_NAMES = {
+      min: "Min",
+      max: "Max",
+      clamp: "Clamp",
+      round: "Round",
+      floor: "Floor",
+      ceiling: "Ceiling",
+      truncate: "Truncate",
+      abs: "Abs",
+      sign: "Sign",
+      sqrt: "Sqrt"
+    };
+    DOUBLE_INTEGRAL_MAGNITUDE = 2 ** 53;
     EMPTY_SUPPLIED_CONSTRUCTOR_FIELDS = [];
   }
 });
@@ -111706,7 +112252,7 @@ var init_registry2 = __esm({
     PROJECT_SCHEMA_CONTRACT = Object.freeze({
       formatVersion: 3,
       contractVersion: "3.13",
-      cliVersion: "0.31.17",
+      cliVersion: "0.32.0",
       projectFileUploadBatchSize: 32,
       documentRecords: {
         member: {
@@ -118301,7 +118847,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.17");
+    console.log("0.32.0");
     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.17",
+  "version": "0.32.0",
   "description": "Neo Compose native project-source CLI with bidirectional sync.",
   "license": "MIT",
   "type": "module",

package/skills/neocompose-cli/SKILL.md

@@ -9,7 +9,7 @@ description: >-
   `@neocompose/cli` or `node cli/bin/neo.mjs` in the neo-compose repository.
 ---
 
-<!-- reviewed-through-cli: 0.31.17 -->
+<!-- reviewed-through-cli: 0.32.0 -->
 
 # Neo Compose CLI
 
@@ -138,7 +138,8 @@ completely before editing:
   variant folders, partial animation overrides, segments, tracks, and NeoFlow
   dialogues.
 - [NeoScript](references/neoscript.md): inline bodies, snippets, nullability,
-  loops, switch, try/catch, ownership, evaluation, and migrations.
+  numeric builtins, loops, switch, try/catch, ownership, evaluation, and
+  migrations.
 - [Commands and synchronization](references/commands-and-sync.md): pull/push,
   conflicts, low-level repair, branches, releases, and history.
 - [CLI development](references/cli-development.md): implementation source of

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.17 -->
+<!-- reviewed-through-cli: 0.32.0 -->
 ```
 
 The quoted version above is checked too, so this instruction cannot go stale

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

@@ -7,6 +7,7 @@ runtime ownership, evaluation, and migrations.
 
 - Inline bodies and snippets
 - Nullability and ownership
+- Numeric builtins
 - Logical operators
 - Loops and transfer
 - Switch
@@ -81,6 +82,27 @@ Save, Session, Setter, or otherwise writable. A constructor writes only its
 `this` instance. A writable structured-leaf field still inherits the receiver's
 effective storage restrictions.
 
+## Numeric builtins
+
+Use the `Math` namespace for numeric utilities with C# names and C# semantics:
+`Min`, `Max`, `Clamp`, `Round`, `Floor`, `Ceiling`, `Truncate`, `Abs`, `Sign`,
+`Sqrt`, and the `PI` and `E` constants.
+
+```neo
+return Math.Clamp(this.Quality + bonus, 0, 10);
+```
+
+Each result follows the arithmetic join of its argument types: all-`int` gives
+`int`, any `float` gives `float`, any `decimal` gives `decimal`, and `decimal`
+never mixes with `float`. `Round`, `Floor`, `Ceiling`, and `Truncate` are the
+language's `float`-to-`int` conversions: they return `int` for `int` and
+`float` input, keep a `decimal` a `decimal`, and reject a non-finite argument
+at runtime. `Round` rounds midpoints to even, matching `decimal.Round(0)`.
+`Sign` always returns `int`; `Sqrt` takes `int` or `float` only.
+
+`Math` is a qualifier, never a type or a value, and the name is reserved: no
+Class, enum, member, parameter, or local may be named `Math`.
+
 ## Logical operators
 
 Use `&&` and `||` with C# precedence: `&&` binds tighter than `||`, and