postcss-calc 11.2.0 → 11.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postcss-calc",
-  "version": "11.2.0",
+  "version": "11.2.1",
   "type": "module",
   "description": "PostCSS plugin to reduce calc()",
   "keywords": [
@@ -42,16 +42,16 @@
     }
   },
   "devDependencies": {
-    "@csstools/css-calc": "^3.3.0",
-    "@types/node": "^26.5.1",
-    "fast-check": "^4.10.0",
+    "@csstools/css-calc": "^3.4.0",
+    "@types/node": "^26.6.1",
+    "fast-check": "^4.10.1",
     "oxfmt": "^0.68.0",
     "oxlint": "^1.83.0",
     "postcss": "^8.5.28",
     "typescript": "~7.0.2"
   },
   "dependencies": {
-    "@csstools/css-tokenizer": "^4.0.0"
+    "@csstools/css-tokenizer": "^4.0.1"
   },
   "peerDependencies": {
     "postcss": "^8.5.28"

package/src/lib/analyze.js

@@ -1,16 +1,32 @@
 import { baseOf } from './convertUnits.js';
-import { addTypes, isFailure, mathFunctions } from './functions.js';
+import {
+  addTypes,
+  failureType,
+  isFailure,
+  isPercentage,
+  mathFunctions,
+  numberType,
+  percentageType,
+  unknownType,
+} from './functions.js';
 import { assertDepth } from './limits.js';
 
 /** @typedef {import('./node.js').Node} Node */
 /** @typedef {import('./functions.js').CalculationType} CalculationType */
+/** @typedef {Extract<CalculationType, {kind: 'dimension'}>} DimensionType */
 
 /** @typedef {'number' | 'unknown' | {dimension: string | null}} AnalysisType */
 /** @typedef {{type: AnalysisType, valid: boolean, unresolved: boolean}} Analysis */
-
-/** @type {CalculationType} */ const numberType = { kind: 'number' };
-/** @type {CalculationType} */ const unknownType = { kind: 'unknown' };
-/** @type {CalculationType} */ const failureType = { kind: 'failure' };
+/**
+ * @typedef {Object} ProductFactors
+ * @property {boolean} valid
+ * @property {boolean} structurallyValid
+ * @property {boolean} hasUnresolved
+ * @property {DimensionType | null} numerator
+ * @property {DimensionType | null} denominator
+ * @property {boolean} hasOpaqueNumerator
+ * @property {boolean} hasOpaqueDenominator
+ */
 
 /**
  * Analyze the original complete tree and return its root summary. Analysis
@@ -34,10 +50,11 @@ function analyzeType(node, depth = 0) {
     case 'Num':
       return resolved(numberType);
     case 'Dim':
-      // Percentages are contextual. Unknown units are opaque, while known
-      // families can still reject px + seconds.
+      // Percentages are contextual; their percent-ness is tracked so a
+      // `% / %` product cancels to a number. Unknown units are opaque, while
+      // known families can still reject px + seconds.
       return node.unit === '%'
-        ? finish(unknownType, true, true)
+        ? finish(percentageType, true, true)
         : resolved({ kind: 'dimension', base: baseOf(node.unit) });
     case 'Ident':
       return markUnresolved(unknownType);
@@ -56,6 +73,7 @@ function analyzeType(node, depth = 0) {
 function analyzeSum(node, depth) {
   let type = null;
   let hasUnknown = false;
+  let hasPercentage = false;
   let valid = true;
   let hasUnresolved = false;
   for (const term of node.terms) {
@@ -65,7 +83,11 @@ function analyzeSum(node, depth) {
     if (isFailure(child.type)) {
       type = failureType;
     } else if (child.type.kind === 'unknown') {
-      hasUnknown = true;
+      // A pure percentage sum stays percentage-typed so a surrounding
+      // product can cancel `% / %`; any other opaque term must widen the
+      // sum back to unknown.
+      if (isPercentage(child.type)) hasPercentage = true;
+      else hasUnknown = true;
     } else if (type === null) {
       type = child.type;
     } else if (!isFailure(type)) {
@@ -75,11 +97,10 @@ function analyzeSum(node, depth) {
   if (type !== null && isFailure(type)) {
     return finish(failureType, false, hasUnresolved);
   }
-  return finish(
-    type ?? (hasUnknown ? unknownType : numberType),
-    valid,
-    hasUnresolved
-  );
+  let fallback = numberType;
+  if (hasUnknown) fallback = unknownType;
+  else if (hasPercentage) fallback = percentageType;
+  return finish(type ?? fallback, valid, hasUnresolved);
 }
 
 /** @param {Extract<Node, {type: 'Product'}>} node @param {number} depth @return {{type: CalculationType, valid: boolean, unresolved: boolean}} */
@@ -88,8 +109,13 @@ function analyzeProduct(node, depth) {
   let denominator = null;
   let valid = true;
   let structurallyValid = true;
-  let hasUnknownNumerator = false;
-  let hasUnknownDenominator = false;
+  // Opaque factors (unknowns and pure percentages) are counted per side so
+  // the pass below can decide whether any unknown remains after cancelling
+  // `% / %` pairs.
+  let opaqueNumerator = 0;
+  let opaqueDenominator = 0;
+  let percentageNumerator = 0;
+  let percentageDenominator = 0;
   let hasUnresolved = false;
   for (const factor of node.factors) {
     const child = analyzeType(factor.node, depth + 1);
@@ -99,8 +125,13 @@ function analyzeProduct(node, depth) {
       continue;
     }
     if (child.type.kind === 'unknown') {
-      if (factor.exponent === 1) hasUnknownNumerator = true;
-      else hasUnknownDenominator = true;
+      if (factor.exponent === 1) {
+        opaqueNumerator++;
+        if (isPercentage(child.type)) percentageNumerator++;
+      } else {
+        opaqueDenominator++;
+        if (isPercentage(child.type)) percentageDenominator++;
+      }
       continue;
     }
     if (child.type.kind !== 'dimension') continue;
@@ -112,10 +143,36 @@ function analyzeProduct(node, depth) {
       else denominator = child.type;
     }
   }
+  // A percentage divided by a percentage is always a plain number: both
+  // operands resolve in the same context, so their contextual type cancels.
+  // Consume one such pair before judging the remaining unknowns so a
+  // surrounding sum does not mistake `% / %` for a length-compatible term.
+  const cancelled = Math.min(percentageNumerator, percentageDenominator);
+  const hasOpaqueNumerator = opaqueNumerator - cancelled > 0;
+  const hasOpaqueDenominator = opaqueDenominator - cancelled > 0;
+  return finishProduct({
+    valid,
+    structurallyValid,
+    hasUnresolved,
+    numerator,
+    denominator,
+    hasOpaqueNumerator,
+    hasOpaqueDenominator,
+  });
+}
+
+/**
+ * Classify a product once its factors are analyzed. Opaque factors can supply
+ * missing type information, but they cannot make an already-invalid
+ * combination of known dimensions valid.
+ * @param {ProductFactors} factors
+ * @return {{type: CalculationType, valid: boolean, unresolved: boolean}}
+ */
+function finishProduct(factors) {
+  const { valid, structurallyValid, hasUnresolved } = factors;
   if (!valid) return finish(failureType, false, hasUnresolved);
-  // Opaque factors can supply missing type information, but they cannot make
-  // an already-invalid combination of known dimensions valid.
   if (!structurallyValid) return finish(failureType, false, hasUnresolved);
+  const { numerator, denominator } = factors;
   if (
     numerator !== null &&
     denominator !== null &&
@@ -127,18 +184,13 @@ function analyzeProduct(node, depth) {
   // only leave that dimension in place (when it resolves to a number) or make
   // the product invalid. It can never make the product a bare number. Keep
   // that known constraint so a surrounding sum can reject `1px * 1% + 1`.
-  const constrained = constrainedNumerator(
-    hasUnknownNumerator,
-    hasUnknownDenominator,
-    numerator,
-    denominator
-  );
+  const constrained = constrainedNumerator(factors);
   if (constrained !== null) {
     return finish(constrained, true, hasUnresolved);
   }
   // Other opaque factors may supply type information that changes how the
   // known dimensions combine once the known factors are structurally valid.
-  if (hasUnknownNumerator || hasUnknownDenominator) {
+  if (factors.hasOpaqueNumerator || factors.hasOpaqueDenominator) {
     return finish(unknownType, true, hasUnresolved);
   }
   if (numerator !== null && denominator !== null) {
@@ -153,23 +205,15 @@ function analyzeProduct(node, depth) {
 }
 
 /**
- * @param {boolean} hasUnknownNumerator
- * @param {boolean} hasUnknownDenominator
- * @param {CalculationType | null} numerator
- * @param {CalculationType | null} denominator
- * @return {CalculationType | null}
+ * @param {ProductFactors} factors
+ * @return {DimensionType | null}
  */
-function constrainedNumerator(
-  hasUnknownNumerator,
-  hasUnknownDenominator,
-  numerator,
-  denominator
-) {
-  return hasUnknownNumerator &&
-    !hasUnknownDenominator &&
-    numerator !== null &&
-    denominator === null
-    ? numerator
+function constrainedNumerator(factors) {
+  return factors.hasOpaqueNumerator &&
+    !factors.hasOpaqueDenominator &&
+    factors.numerator !== null &&
+    factors.denominator === null
+    ? factors.numerator
     : null;
 }
 

package/src/lib/functions.js

@@ -14,13 +14,23 @@ import { simplifyLog } from './simplify/log.js';
 import { simplifyHypot } from './simplify/hypot.js';
 
 /** @typedef {import('./node.js').Node} Node */
-/** @typedef {{kind: 'number'} | {kind: 'dimension', base: string | null} | {kind: 'unknown'} | {kind: 'failure'}} CalculationType */
+/**
+ * `percent` marks a value that resolves in the same percentage context as its
+ * peers (a pure percentage). It is only produced at leaves, by abs(), and by
+ * homogeneous sums and calls — never by a product, where an unpaired
+ * percentage could no longer cancel against anything.
+ * @typedef {{kind: 'number'} | {kind: 'dimension', base: string | null} | {kind: 'unknown', percent?: true} | {kind: 'failure'}} CalculationType
+ */
 /** @typedef {(name: string, args: Node[]) => Node} MathSimplifier */
 /** @typedef {(args: CalculationType[], nodes: Node[]) => CalculationType} TypeAnalyzer */
 /** @typedef {{analyze: TypeAnalyzer, simplify?: MathSimplifier, isKeyword?: (node: Node, index: number) => boolean, calculation?: boolean}} MathFunction */
 
 /** @type {CalculationType} */ const numberType = { kind: 'number' };
 /** @type {CalculationType} */ const unknownType = { kind: 'unknown' };
+/** @type {CalculationType} */ const percentageType = {
+  kind: 'unknown',
+  percent: true,
+};
 /** @type {CalculationType} */ const failureType = { kind: 'failure' };
 
 /** @param {CalculationType} type @return {boolean} */
@@ -28,10 +38,23 @@ function isFailure(type) {
   return type.kind === 'failure';
 }
 
+/** @param {CalculationType} type @return {boolean} */
+function isPercentage(type) {
+  return type.kind === 'unknown' && type.percent === true;
+}
+
 /** @param {CalculationType} a @param {CalculationType} b @return {CalculationType} */
 function addTypes(a, b) {
   if (isFailure(a) || isFailure(b)) return failureType;
-  if (a.kind === 'unknown' || b.kind === 'unknown') return unknownType;
+  if (a.kind === 'unknown' || b.kind === 'unknown') {
+    // A pure percentage keeps its contextual type so a surrounding product
+    // can cancel `% / %`; mixing it with any other opaque operand loses the
+    // guarantee that it resolves in the same context as its peers. A known
+    // number + percentage sum is likewise kept unknown and valid: the spec
+    // resolves the percentage against its surrounding context, which this
+    // coarse type model does not track.
+    return isPercentage(a) && isPercentage(b) ? percentageType : unknownType;
+  }
   if (a.kind === 'number' && b.kind === 'number') return numberType;
   if (a.kind === 'dimension' && b.kind === 'dimension') {
     if (a.base === null || b.base === null) return unknownType;
@@ -129,9 +152,11 @@ function analyzeRound(args, nodes) {
 /** @param {CalculationType[]} args @return {CalculationType} */
 function analyzeAtan2(args) {
   const type = matchingArguments(args, 2, 2);
-  return isFailure(type) || type.kind === 'unknown'
-    ? type
-    : { kind: 'dimension', base: 'angle' };
+  if (isFailure(type)) return type;
+  // The type table gives atan2() «["angle" → 1]»; an unresolved result is
+  // plain unknown, never the percentage of its arguments.
+  if (type.kind === 'unknown') return unknownType;
+  return { kind: 'dimension', base: 'angle' };
 }
 
 /** @param {CalculationType[]} args @return {CalculationType} */
@@ -354,11 +379,16 @@ function hasPotentialMathFunction(value) {
 
 export {
   addTypes,
-  mathFunctions,
-  lookupMathFunction,
-  QUICK_MATH_TEST,
-  isFailure,
+  failureType,
+  hasPotentialMathFunction,
   isCalculationFunction,
+  isFailure,
+  isPercentage,
   isSupportedMathFunction,
-  hasPotentialMathFunction,
+  lookupMathFunction,
+  mathFunctions,
+  numberType,
+  percentageType,
+  QUICK_MATH_TEST,
+  unknownType,
 };

package/src/lib/node.js

@@ -215,7 +215,7 @@ function negate(node) {
   }
   if (node.type === 'Sum') {
     // A grouped sum may contain opaque terms whose meaning depends on the
-    // surrounding context. Keep the group intact so `-(a + b)` cannot turn
+    // surrounding context. Keep the group intact so `-1 * (a + b)` cannot turn
     // into `-a - b` while it is still unresolved.
     if (node.grouped) {
       return mkSum([{ sign: -1, node }]);

package/src/lib/parser.js

@@ -1,16 +1,7 @@
 // Pratt parser over native @csstools/css-tokenizer tokens.
 import { TokenType as CssType } from '@csstools/css-tokenizer';
 import { baseOf } from './convertUnits.js';
-import {
-  call,
-  dim,
-  ident,
-  mkProduct,
-  mkSum,
-  negate,
-  num,
-  opaqueCall,
-} from './node.js';
+import { call, dim, ident, mkProduct, mkSum, num, opaqueCall } from './node.js';
 import { isCalculationFunction, isSupportedMathFunction } from './functions.js';
 import { assertDepth } from './limits.js';
 import { CSS_NUMBER_PREFIX } from './regex.js';
@@ -293,11 +284,10 @@ function parsePrefix(input, cursor, token, depth) {
             ? { ...expression, grouped: true }
             : expression;
         }
-        case '-':
-          return negate(parseExpr(input, cursor, 7, depth + 1));
-        case '+':
-          return parseExpr(input, cursor, 7, depth + 1);
       }
+    // No unary `+`/`-` production exists in the <calc-value> grammar; a
+    // sign is only valid inside a number/dimension token or as a binary
+    // operator. `-(...)` therefore fails to parse and is preserved.
   }
   throw new Error(`Unexpected token "${token.raw}" at position ${token.pos}`);
 }

package/src/lib/serialize.js

@@ -5,6 +5,7 @@
 import { serializeComponents } from './opaque.js';
 import { checkCalculationDepth } from './limits.js';
 import { isCalculationFunction } from './functions.js';
+import { num } from './node.js';
 
 /**
  * @typedef {import('./node.js').Node} Node
@@ -23,20 +24,73 @@ import { isCalculationFunction } from './functions.js';
 const SUM_PRECEDENCE = 1;
 const PRODUCT_PRECEDENCE = 2;
 const ATOMIC_PRECEDENCE = 3;
-// Unary minus binds more tightly than a sum but has the same atomic boundary
-// for deciding whether `-x` needs parentheses.
+// Negation (-1 * ...) binds more tightly than a sum but has the same atomic boundary
+// for deciding whether the operand needs parentheses.
 const UNARY_PRECEDENCE = ATOMIC_PRECEDENCE;
 const NOISE_FLOOR = 1e-12;
 
 /**
- * Decimal rounding with "round half away from zero" (e.g. 1.005 at precision 2 -> 1.01).
+ * Divide a decimal digit string by 10^k, rounding half away from zero, and
+ * return the resulting integer digit string. `digits` has no leading zeros.
+ * @param {string} digits
+ * @param {number} k
+ * @return {string}
+ */
+function divideByPowerOfTen(digits, k) {
+  // 0x30/0x35/0x39 are the char codes of '0'/'5'/'9'.
+  if (digits.length <= k) {
+    return digits.length === k && digits.charCodeAt(0) >= 0x35 ? '1' : '0';
+  }
+  const cut = digits.length - k;
+  if (digits.charCodeAt(cut) < 0x35) return digits.slice(0, cut);
+  // Round up and propagate the carry through trailing nines.
+  let index = cut - 1;
+  while (index >= 0 && digits.charCodeAt(index) === 0x39) index--;
+  if (index < 0) return `1${'0'.repeat(cut)}`;
+  return `${digits.slice(0, index)}${String.fromCharCode(
+    digits.charCodeAt(index) + 1
+  )}${'0'.repeat(cut - index - 1)}`;
+}
+
+/**
+ * Round the shortest decimal representation of a non-negative double to `p`
+ * fractional digits, half away from zero.
  *
- * Binary floating-point (IEEE-754) cannot represent many decimal fractions exactly
- * (e.g. 1.005 is binary 1.004999999999999893...), causing arithmetic formulas like
- * `Math.round(v * 100) / 100` to round down to 1.00. Exponential notation string shifting
- * (`1.005e2` -> `100.5`) lets the ECMAScript string-to-number parser read the exact
- * intended decimal value before rounding.
+ * `Number(text + 'e' + p)` reads the exact intended decimal (so `1.005` at
+ * precision 2 becomes `1.01`), but it is only exact while the shifted value
+ * fits in `Number.MAX_SAFE_INTEGER`; beyond that the intermediate double
+ * rounds and can move the rounding boundary (e.g. `312834450754803.44` at
+ * precision 1 or 6 drifted to `312834450754803.5`). Round the decimal digits
+ * directly instead.
  *
+ * @param {number} abs
+ * @param {number} p
+ * @return {number}
+ */
+function roundDecimal(abs, p) {
+  const text = String(abs);
+  const eIdx = text.indexOf('e');
+  const mantissa = eIdx === -1 ? text : text.slice(0, eIdx);
+  let exponent = eIdx === -1 ? 0 : Number(text.slice(eIdx + 1));
+  const dot = mantissa.indexOf('.');
+  let digits = mantissa;
+  if (dot !== -1) {
+    digits = mantissa.slice(0, dot) + mantissa.slice(dot + 1);
+    exponent -= mantissa.length - dot - 1;
+  }
+
+  // value = digits * 10^exponent, so the shortest decimal has -exponent
+  // fractional digits when it is smaller than 1.
+  if (exponent >= -p) return abs;
+
+  let start = 0;
+  while (start < digits.length - 1 && digits.charCodeAt(start) === 0x30)
+    start++;
+  const rounded = divideByPowerOfTen(digits.slice(start), -(exponent + p));
+  return Number(`${rounded}e-${p}`);
+}
+
+/**
  * @param {number} v
  * @param {number | false} prec
  * @return {number}
@@ -53,36 +107,9 @@ function round(v, prec) {
   // or exponent overflows into Infinity/NaN (e.g. exponent + prec > 308).
   const p = Math.min(100, Math.max(0, Math.trunc(prec)));
   const sign = v < 0 ? -1 : 1;
-  let rounded;
-
-  if (p === 0) {
-    // Fast path: rounding to integer with "round half away from zero".
-    rounded = sign * Math.round(abs);
-  } else {
-    // Avoid .split('e') allocations: for numbers between 1e-6 and MAX_SAFE_INTEGER,
-    // String(abs) never contains exponential notation ('e').
-    const absStr = String(abs);
-    const eIdx = absStr.indexOf('e');
-    let shifted;
-    if (eIdx === -1) {
-      shifted = Math.round(Number(absStr + 'e' + p));
-    } else {
-      const mantissa = absStr.slice(0, eIdx);
-      const exponent = Number(absStr.slice(eIdx + 1));
-      shifted = Math.round(Number(mantissa + 'e' + (exponent + p)));
-    }
-
-    // shifted is an integer. It only contains exponential notation ('e') if >= 1e21.
-    if (shifted >= 1e21) {
-      const shiftedStr = String(shifted);
-      const seIdx = shiftedStr.indexOf('e');
-      const sMantissa = shiftedStr.slice(0, seIdx);
-      const sExponent = Number(shiftedStr.slice(seIdx + 1));
-      rounded = sign * Number(sMantissa + 'e' + (sExponent - p));
-    } else {
-      rounded = sign * Number(shifted + 'e-' + p);
-    }
-  }
+  // Fast path: rounding to integer with "round half away from zero".
+  const rounded =
+    p === 0 ? sign * Math.round(abs) : sign * roundDecimal(abs, p);
 
   // Preserve non-zero values smaller than precision (e.g. 1/1000000) from collapsing
   // to zero, while still snapping true floating-point dust (< 1e-12) to zero.
@@ -163,20 +190,21 @@ function emitFiniteScalar(node, session, value) {
  */
 function emitScalar(node, session, value) {
   const buffer = session.buffer;
-  if (Object.is(node.value, -0)) emitSignedZero(buffer, node);
-  else if (isDegenerate(node.value)) {
+  const effective = value ?? node.value;
+  if (Object.is(effective, -0)) emitSignedZero(buffer, node);
+  else if (isDegenerate(effective)) {
     if (node.type === 'Dim') {
       buffer.push(
         'calc(',
-        degenerateKeyword(node.value),
+        degenerateKeyword(effective),
         ' * 1',
         node.rawUnit ?? node.unit,
         ')'
       );
     } else {
-      buffer.push(degenerateKeyword(node.value));
+      buffer.push(degenerateKeyword(effective));
     }
-  } else emitFiniteScalar(node, session, value);
+  } else emitFiniteScalar(node, session, effective);
 }
 
 /**
@@ -224,15 +252,13 @@ function needsParentheses(node, parentPrecedence, groupedRequired) {
  * @param {ReturnType<typeof makeContext>} session
  * @param {number} [parentPrecedence]
  * @param {boolean} [groupedRequired]
- * @param {number} [scalarValueOverride]
  * @return {void}
  */
 function emitNode(
   node,
   session,
   parentPrecedence = 0,
-  groupedRequired = false,
-  scalarValueOverride
+  groupedRequired = false
 ) {
   const parenthesized = needsParentheses(
     node,
@@ -240,22 +266,21 @@ function emitNode(
     groupedRequired
   );
   if (parenthesized) session.buffer.push('(');
-  emitNodeBody(node, session, scalarValueOverride);
+  emitNodeBody(node, session);
   if (parenthesized) session.buffer.push(')');
 }
 
 /**
  * @param {Node} node
  * @param {ReturnType<typeof makeContext>} session
- * @param {number} [scalarValueOverride]
  * @return {void}
  */
-function emitNodeBody(node, session, scalarValueOverride) {
+function emitNodeBody(node, session) {
   const buffer = session.buffer;
   switch (node.type) {
     case 'Num':
     case 'Dim':
-      emitScalar(node, session, scalarValueOverride);
+      emitScalar(node, session);
       return;
     case 'Ident':
       buffer.push(node.rawName ?? node.name);
@@ -306,18 +331,31 @@ function emitOpaqueCall(node, session, callNameOverride) {
   buffer.push(')');
 }
 
+/**
+ * Whether a scalar node is strictly negative after precision rounding
+ * (excluding signed zero and sub-precision values that round to zero).
+ * @param {Node} node
+ * @param {number | false} precision
+ * @return {node is import('./node.js').Num | import('./node.js').Dim}
+ */
+function isEffectivelyNegative(node, precision) {
+  return (
+    isScalar(node) &&
+    !Object.is(node.value, -0) &&
+    Number.isFinite(node.value) &&
+    round(node.value, precision) < 0
+  );
+}
+
 /**
  * @param {import('./node.js').SumTerm} term
  * @param {1 | -1} multiplier
+ * @param {number | false} precision
  * @return {1 | -1}
- * */
-function termSign(term, multiplier) {
+ */
+function termSign(term, multiplier, precision) {
   let sign = /** @type {1 | -1} */ (term.sign * multiplier);
-  if (
-    isScalar(term.node) &&
-    Number.isFinite(term.node.value) &&
-    term.node.value < 0
-  ) {
+  if (isEffectivelyNegative(term.node, precision)) {
     sign = /** @type {1 | -1} */ (-sign);
   }
   return sign;
@@ -327,14 +365,13 @@ function termSign(term, multiplier) {
  * @param {import('./node.js').SumTerm} term
  * @param {ReturnType<typeof makeContext>} session
  * @param {1 | -1} sign
- * @param {number | undefined} scalarValueOverride
  * @return {void}
  */
-function emitSumTerm(term, session, sign, scalarValueOverride) {
+function emitSumTerm(term, session, sign) {
   if (sign === 1) {
-    emitNode(term.node, session, SUM_PRECEDENCE, true, scalarValueOverride);
+    emitNode(term.node, session, SUM_PRECEDENCE, true);
   } else {
-    emitLeadingNeg(term.node, session, scalarValueOverride);
+    emitLeadingNeg(term.node, session);
   }
 }
 
@@ -349,25 +386,38 @@ function emitSumTerms(terms, session, multiplier = 1) {
   for (let i = 0; i < terms.length; i++) {
     const term = terms[i];
     const termNode = term.node;
-    const scalar = isScalar(termNode);
-    const negativeScalar =
-      scalar && Number.isFinite(termNode.value) && termNode.value < 0;
-    let sign = /** @type {1 | -1} */ (term.sign * multiplier);
-    if (negativeScalar) sign = /** @type {1 | -1} */ (-sign);
-    const scalarValueOverride = negativeScalar ? -termNode.value : undefined;
-    if (i === 0) {
-      if (scalar) {
-        if (sign === -1) buffer.push('-');
-        emitScalar(termNode, session, scalarValueOverride);
+    if (isScalar(termNode)) {
+      const effectiveVal = term.sign * multiplier * termNode.value;
+      if (Object.is(effectiveVal, -0)) {
+        if (i > 0) buffer.push(' + ');
+        emitSignedZero(buffer, termNode);
+      } else if (isDegenerate(effectiveVal)) {
+        const sign = /** @type {1 | -1} */ (term.sign * multiplier);
+        if (i === 0) {
+          if (sign === -1) buffer.push('-');
+          emitScalar(termNode, session);
+        } else {
+          buffer.push(sign === 1 ? ' + ' : ' - ');
+          emitScalar(termNode, session);
+        }
       } else {
-        emitSumTerm(term, session, sign, scalarValueOverride);
+        const rounded = round(effectiveVal, session.precision);
+        if (rounded < 0) {
+          if (i === 0) buffer.push('-');
+          else buffer.push(' - ');
+          emitRoundedScalar(termNode, buffer, -rounded);
+        } else {
+          if (i > 0) buffer.push(' + ');
+          emitRoundedScalar(termNode, buffer, rounded);
+        }
       }
       continue;
     }
-    buffer.push(sign === 1 ? ' + ' : ' - ');
-    if (scalar) {
-      emitScalar(termNode, session, scalarValueOverride);
+    const sign = /** @type {1 | -1} */ (term.sign * multiplier);
+    if (i === 0) {
+      emitSumTerm(term, session, sign);
     } else {
+      buffer.push(sign === 1 ? ' + ' : ' - ');
       emitNode(termNode, session, SUM_PRECEDENCE, true);
     }
   }
@@ -381,30 +431,24 @@ function emitSum(sum, session) {
 /**
  * @param {Node} node
  * @param {ReturnType<typeof makeContext>} session
- * @param {number} [scalarValueOverride]
  * @return {void}
  */
-function emitLeadingNeg(node, session, scalarValueOverride) {
-  if (
-    node.type === 'Product' &&
-    node.factors.length > 0 &&
-    node.factors[0].exponent === 1 &&
-    node.factors[0].node.type === 'Num' &&
-    Number.isFinite(node.factors[0].node.value) &&
-    node.factors[0].node.value !== 0
-  ) {
-    const head = node.factors[0].node;
-    emitProductFactors(node.factors, session, 1, -head.value, head);
+function emitLeadingNeg(node, session) {
+  if (node.type === 'Product') {
+    if (
+      node.factors.length > 0 &&
+      node.factors[0].exponent === 1 &&
+      node.factors[0].node.type === 'Num'
+    ) {
+      const head = node.factors[0].node;
+      emitProductFactors(node.factors, session, 1, -head.value, head);
+      return;
+    }
+    emitProductFactors(node.factors, session, 0, -1, num(-1));
     return;
   }
-  session.buffer.push('-');
-  emitNode(
-    node,
-    session,
-    UNARY_PRECEDENCE,
-    false,
-    isScalar(node) ? scalarValueOverride : undefined
-  );
+  session.buffer.push('-1 * ');
+  emitNode(node, session, UNARY_PRECEDENCE, false);
 }
 
 /**
@@ -459,9 +503,9 @@ function emitRootExpr(node, session) {
     node.type === 'Sum' &&
     node.grouped &&
     node.terms.length > 1 &&
-    termSign(node.terms[0], 1) === -1
+    termSign(node.terms[0], 1, session.precision) === -1
   ) {
-    session.buffer.push('-(');
+    session.buffer.push('-1 * (');
     emitSumTerms(node.terms, session, -1);
     session.buffer.push(')');
     return;
@@ -500,9 +544,9 @@ function emitMathResult(node, session, wrapper) {
     node.type === 'Sum' &&
     node.grouped &&
     node.terms.length > 1 &&
-    termSign(node.terms[0], 1) === -1
+    termSign(node.terms[0], 1, session.precision) === -1
   ) {
-    session.buffer.push(wrapper, '(-(');
+    session.buffer.push(wrapper, '(-1 * (');
     emitSumTerms(node.terms, session, -1);
     session.buffer.push('))');
     return;

package/types/lib/analyze.d.ts

@@ -1,5 +1,8 @@
 export type Node = import('./node.js').Node;
 export type CalculationType = import('./functions.js').CalculationType;
+export type DimensionType = Extract<CalculationType, {
+    kind: 'dimension';
+}>;
 export type AnalysisType = 'number' | 'unknown' | {
     dimension: string | null;
 };
@@ -8,6 +11,30 @@ export type Analysis = {
     valid: boolean;
     unresolved: boolean;
 };
+export type ProductFactors = {
+    valid: boolean;
+    structurallyValid: boolean;
+    hasUnresolved: boolean;
+    numerator: DimensionType | null;
+    denominator: DimensionType | null;
+    hasOpaqueNumerator: boolean;
+    hasOpaqueDenominator: boolean;
+};
+/** @typedef {import('./node.js').Node} Node */
+/** @typedef {import('./functions.js').CalculationType} CalculationType */
+/** @typedef {Extract<CalculationType, {kind: 'dimension'}>} DimensionType */
+/** @typedef {'number' | 'unknown' | {dimension: string | null}} AnalysisType */
+/** @typedef {{type: AnalysisType, valid: boolean, unresolved: boolean}} Analysis */
+/**
+ * @typedef {Object} ProductFactors
+ * @property {boolean} valid
+ * @property {boolean} structurallyValid
+ * @property {boolean} hasUnresolved
+ * @property {DimensionType | null} numerator
+ * @property {DimensionType | null} denominator
+ * @property {boolean} hasOpaqueNumerator
+ * @property {boolean} hasOpaqueDenominator
+ */
 /**
  * Analyze the original complete tree and return its root summary. Analysis
  * validates and classifies the tree; it is not a rewrite plan.

package/types/lib/functions.d.ts

@@ -6,6 +6,7 @@ export type CalculationType = {
     base: string | null;
 } | {
     kind: 'unknown';
+    percent?: true;
 } | {
     kind: 'failure';
 };
@@ -17,8 +18,25 @@ export type MathFunction = {
     isKeyword?: (node: Node, index: number) => boolean;
     calculation?: boolean;
 };
+/** @typedef {import('./node.js').Node} Node */
+/**
+ * `percent` marks a value that resolves in the same percentage context as its
+ * peers (a pure percentage). It is only produced at leaves, by abs(), and by
+ * homogeneous sums and calls — never by a product, where an unpaired
+ * percentage could no longer cancel against anything.
+ * @typedef {{kind: 'number'} | {kind: 'dimension', base: string | null} | {kind: 'unknown', percent?: true} | {kind: 'failure'}} CalculationType
+ */
+/** @typedef {(name: string, args: Node[]) => Node} MathSimplifier */
+/** @typedef {(args: CalculationType[], nodes: Node[]) => CalculationType} TypeAnalyzer */
+/** @typedef {{analyze: TypeAnalyzer, simplify?: MathSimplifier, isKeyword?: (node: Node, index: number) => boolean, calculation?: boolean}} MathFunction */
+/** @type {CalculationType} */ declare const numberType: CalculationType;
+/** @type {CalculationType} */ declare const unknownType: CalculationType;
+/** @type {CalculationType} */ declare const percentageType: CalculationType;
+/** @type {CalculationType} */ declare const failureType: CalculationType;
 /** @param {CalculationType} type @return {boolean} */
 declare function isFailure(type: CalculationType): boolean;
+/** @param {CalculationType} type @return {boolean} */
+declare function isPercentage(type: CalculationType): boolean;
 /** @param {CalculationType} a @param {CalculationType} b @return {CalculationType} */
 declare function addTypes(a: CalculationType, b: CalculationType): CalculationType;
 declare const mathFunctions: Map<string, MathFunction>;
@@ -37,4 +55,4 @@ declare function isCalculationFunction(name: string): boolean;
 declare function isSupportedMathFunction(name: string): boolean;
 /** @param {string} value @return {boolean} */
 declare function hasPotentialMathFunction(value: string): boolean;
-export { addTypes, mathFunctions, lookupMathFunction, QUICK_MATH_TEST, isFailure, isCalculationFunction, isSupportedMathFunction, hasPotentialMathFunction, };
+export { addTypes, failureType, hasPotentialMathFunction, isCalculationFunction, isFailure, isPercentage, isSupportedMathFunction, lookupMathFunction, mathFunctions, numberType, percentageType, QUICK_MATH_TEST, unknownType, };

package/src/lib/calculation-type.js

@@ -1,25 +0,0 @@
-// Compatibility facade for the former calculation-type module. New code uses
-// analyze() for the complete result and limits.js for depth policy.
-
-import { analyze } from './analyze.js';
-import { MAX_CALCULATION_DEPTH, checkCalculationDepth } from './limits.js';
-
-/** @typedef {import('./node.js').Node} Node */
-
-/** @typedef {{kind: 'number'} | {kind: 'dimension', base: string | null} | {kind: 'unknown'} | {kind: 'failure'}} CalculationType */
-
-/** @param {Node} node @return {CalculationType} */
-function checkCalculationType(node) {
-  const result = analyze(node);
-  if (!result.valid) return { kind: 'failure' };
-  if (result.type === 'number') return { kind: 'number' };
-  if (result.type === 'unknown') return { kind: 'unknown' };
-  return { kind: 'dimension', base: result.type.dimension };
-}
-
-export {
-  MAX_CALCULATION_DEPTH,
-  checkCalculationDepth,
-  checkCalculationType,
-  analyze,
-};