postcss-calc 11.1.2 → 11.2.1

package/src/lib/serialize.js

@@ -1,9 +1,11 @@
 // Spec: https://www.w3.org/TR/css-values-4/#serialize-a-calculation-tree
 // Outer calc() is added when the top-level result contains an arithmetic
-// operator, or when a finite scalar is negative.
+// operator, or when a finite scalar needs context-sensitive CSS semantics.
 
-import { num, dim } from './node.js';
-import { getComponents, serializeComponents } from './opaque.js';
+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
@@ -13,324 +15,725 @@ import { getComponents, serializeComponents } from './opaque.js';
  * @typedef {object} SerializeOptions
  * @property {number | false} [precision] Decimal places for numbers. `false` disables rounding. Default 5.
  * @property {string} [calcName] Wrapper name to use when `calc()` is needed. Default `'calc'`.
- * @property {boolean} [unwrapSingleNegativeNumber] Serialize finite negative scalars without a wrapper. Internal selector-only mode.
+ * @property {boolean} [unwrapSingleNegativeNumber] Deprecated alias for `unwrapSingleValue`.
+ * @property {boolean} [unwrapSingleValue] Serialize fully resolved finite scalar results without calculation syntax.
  */
 
-// Below this is float noise, not a value: `0.1 + 0.2 - 0.3` is 5.5e-17.
+// The AST is canonical: sums and products are flat, so these precedence
+// levels cover every binary expression
+const SUM_PRECEDENCE = 1;
+const PRODUCT_PRECEDENCE = 2;
+const ATOMIC_PRECEDENCE = 3;
+// 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;
 
 /**
- * Rounding to `prec` decimal places turns `calc(1/1000000)` into `0`, and a
- * `0` in CSS is often a switch, not a small number (`flex-grow: 0` never
- * grows). So when a value is too small for `prec`, keep its significant digits
- * instead: `1/1000000` -> `0.000001`, `1/3000000` -> `3.3333e-7`.
+ * 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.
+ *
+ * `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}
  */
 function round(v, prec) {
-  if (prec === false) {
-    return v;
-  }
-  const m = Math.pow(10, prec);
-  const rounded = Math.round(v * m) / m;
-  if (rounded === 0 && Math.abs(v) > NOISE_FLOOR) {
-    // toPrecision needs at least one significant digit; `prec` may be 0.
-    return Number(v.toPrecision(Math.max(prec, 1)));
+  if (prec === false || !Number.isFinite(v)) return v;
+  if (Object.is(v, -0) || v === 0) return v;
+  const abs = Math.abs(v);
+  // Numbers >= MAX_SAFE_INTEGER (2^53 - 1) cannot represent fractional values, and
+  // integers already have 0 fractional places. Bypassing them avoids float drift.
+  if (abs >= Number.MAX_SAFE_INTEGER || Number.isInteger(v)) return v;
+
+  // Clamp precision to [0, 100] integer to prevent NaN from fractional precisions
+  // 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;
+  // 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.
+  if (rounded === 0 && abs > NOISE_FLOOR) {
+    return Number(v.toPrecision(Math.max(p, 1)));
   }
   return rounded;
 }
 
 // §10.13 / §10.7.2: Infinity/NaN serialize as canonical keywords.
-/**
- * @param {number} v
- * @return {boolean}
- */
+/** @param {number} v @return {boolean} */
 function isDegenerate(v) {
   return !Number.isFinite(v) || Number.isNaN(v);
 }
 
-/**
- * @param {number} v
- * @return {string}
- */
+/** @param {number} v @return {string} */
 function degenerateKeyword(v) {
-  if (Number.isNaN(v)) {
-    return 'NaN';
-  }
+  if (Number.isNaN(v)) return 'NaN';
   return v > 0 ? 'infinity' : '-infinity';
 }
 
-/**
- * Serialize a finite CSS number. CSS numbers may omit the zero before a
- * fractional value between -1 and 1 (`.5`, `-.5`). Scientific notation is
- * left untouched because it already has no leading zero to remove.
- *
- * @param {number} v
- * @return {string}
- */
+/** @param {number} v @return {string} */
 function serializeNumber(v) {
+  if (Object.is(v, -0)) return '0';
   const text = String(v);
-  if (text.startsWith('0.')) {
-    return text.slice(1);
-  }
-  if (text.startsWith('-0.')) {
-    return `-${text.slice(2)}`;
-  }
+  if (text.startsWith('0.')) return text.slice(1);
+  if (text.startsWith('-0.')) return `-${text.slice(2)}`;
   return text;
 }
 
+/** @param {SerializeOptions} opts @return {'standard' | 'unwrap-all'} */
+function normalizeScalarPolicy(opts) {
+  return opts.unwrapSingleValue || opts.unwrapSingleNegativeNumber
+    ? 'unwrap-all'
+    : 'standard';
+}
+
 /**
- * Round and serialize a finite scalar once so callers can use the same value
- * to decide its syntactic context and render its text.
- *
  * @param {import('./node.js').Num | import('./node.js').Dim} node
- * @param {number | false} prec
- * @return {{value: number, text: string}}
+ * @param {number | false} precision
+ * @param {number} [value]
+ * @return {number}
  */
-function serializeScalar(node, prec) {
-  const value = round(node.value, prec);
-  const text = `${serializeNumber(value)}${node.type === 'Dim' ? (node.rawUnit ?? node.unit) : ''}`;
-  return { value, text };
+function roundedScalarValue(node, precision, value) {
+  return round(value ?? node.value, precision);
 }
 
 /**
- * @param {Node} node
- * @param {SerializeOptions} [opts]
- * @return {string}
+ * @param {import('./node.js').Num | import('./node.js').Dim} node
+ * @param {string[]} buffer
+ * @param {number} value
+ * @return {void}
  */
-function serialize(node, opts = {}) {
-  const prec = opts.precision ?? 5;
-  const calcName = opts.calcName ?? 'calc';
-
-  // §10.13: top-level Infinity/NaN wrap in calc(); dim degenerates carry
-  // the unit as `<keyword> * 1<unit>` so the result keeps its type.
-  if (node.type === 'Num' && isDegenerate(node.value)) {
-    return `${calcName}(${degenerateKeyword(node.value)})`;
-  }
-  if (node.type === 'Dim' && isDegenerate(node.value)) {
-    return `${calcName}(${degenerateKeyword(node.value)} * 1${node.rawUnit ?? node.unit})`;
+function emitRoundedScalar(node, buffer, value) {
+  buffer.push(serializeNumber(value));
+  if (node.type === 'Dim') {
+    buffer.push(node.rawUnit ?? node.unit);
   }
+}
+
+/**
+ * @param {import('./node.js').Num | import('./node.js').Dim} node
+ * @param {ReturnType<typeof makeContext>} session
+ * @param {number} [value]
+ * @return {number}
+ */
+function emitFiniteScalar(node, session, value) {
+  const rounded = roundedScalarValue(node, session.precision, value);
+  emitRoundedScalar(node, session.buffer, rounded);
+  return rounded;
+}
 
-  if (node.type === 'Num' || node.type === 'Dim') {
-    const scalar = serializeScalar(node, prec);
-
-    // A finite negative scalar must stay inside calc() so CSS parses it as a
-    // calculation result (and can apply range clamping) rather than as an
-    // invalid bare value. Base this on the serialized value so tiny negative
-    // floating-point noise that rounds to zero does not get wrapped.
-    if (scalar.value < 0) {
-      return opts.unwrapSingleNegativeNumber
-        ? scalar.text
-        : `${calcName}(${scalar.text})`;
+/**
+ * @param {import('./node.js').Num | import('./node.js').Dim} node
+ * @param {ReturnType<typeof makeContext>} session
+ * @param {number} [value]
+ * @return {void}
+ */
+function emitScalar(node, session, value) {
+  const buffer = session.buffer;
+  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(effective),
+        ' * 1',
+        node.rawUnit ?? node.unit,
+        ')'
+      );
+    } else {
+      buffer.push(degenerateKeyword(effective));
     }
+  } else emitFiniteScalar(node, session, effective);
+}
 
-    return scalar.text;
-  }
+/**
+ * @param {string[]} buffer
+ * @param {import('./node.js').Num | import('./node.js').Dim} node
+ * @return {void}
+ */
+function emitSignedZero(buffer, node) {
+  const unit = node.type === 'Dim' ? (node.rawUnit ?? node.unit) : '';
+  buffer.push('calc(-1 * 0', unit, ')');
+}
 
-  // A grouped sum with a leading negative term is the canonical result of
-  // negating a parenthesized expression. Re-invert its terms for the body so
-  // the grouping survives as `-(...)` instead of becoming `-a - b`.
-  if (
-    node.type === 'Sum' &&
-    node.grouped &&
-    node.terms.length > 1 &&
-    displaySign(node.terms[0]).sign === -1
-  ) {
-    const invertedTerms = node.terms.map((t) => ({
-      sign: /** @type {1 | -1} */ (-t.sign),
-      node: t.node,
-    }));
-    return `${calcName}(-(${serializeSumTerms(invertedTerms, prec)}))`;
-  }
+/** @param {Node} node @return {node is import('./node.js').Num | import('./node.js').Dim} */
+function isScalar(node) {
+  return node.type === 'Num' || node.type === 'Dim';
+}
 
-  if (node.type === 'Ident' || node.type === 'Call') {
-    return serializeExpr(node, prec);
-  }
+/** @param {Node} node @return {node is import('./node.js').Num | import('./node.js').Dim} */
+function isSignedZero(node) {
+  return isScalar(node) ? Object.is(node.value, -0) : false;
+}
 
-  // Single-term Sum is the canonical form for `-var(--x)` / `-(a*b)` —
-  // sign=-1 around an opaque node. Signed leaves live in Num/Dim directly.
-  if (node.type === 'Sum' && node.terms.length === 1) {
-    return `${calcName}(${serializeLeadingNeg(node.terms[0].node, prec)})`;
-  }
+/** @param {Node} node @return {number} */
+function precedence(node) {
+  if (node.type === 'Sum') return SUM_PRECEDENCE;
+  if (node.type === 'Product') return PRODUCT_PRECEDENCE;
+  return ATOMIC_PRECEDENCE;
+}
 
-  return `${calcName}(${serializeExpr(node, prec)})`;
+/**
+ * @param {Node} node
+ * @param {number} parentPrecedence
+ * @param {boolean} groupedRequired
+ * @return {boolean}
+ */
+function needsParentheses(node, parentPrecedence, groupedRequired) {
+  return (
+    precedence(node) < parentPrecedence ||
+    (node.type === 'Sum' && node.grouped === true && groupedRequired === true)
+  );
 }
 
-// --- Inside calc() expression --------------------------------------------
+/**
+ * @param {Node} node
+ * @param {ReturnType<typeof makeContext>} session
+ * @param {number} [parentPrecedence]
+ * @param {boolean} [groupedRequired]
+ * @return {void}
+ */
+function emitNode(
+  node,
+  session,
+  parentPrecedence = 0,
+  groupedRequired = false
+) {
+  const parenthesized = needsParentheses(
+    node,
+    parentPrecedence,
+    groupedRequired
+  );
+  if (parenthesized) session.buffer.push('(');
+  emitNodeBody(node, session);
+  if (parenthesized) session.buffer.push(')');
+}
 
 /**
  * @param {Node} node
- * @param {number | false} prec
- * @return {string}
+ * @param {ReturnType<typeof makeContext>} session
+ * @return {void}
  */
-function serializeExpr(node, prec) {
+function emitNodeBody(node, session) {
+  const buffer = session.buffer;
   switch (node.type) {
     case 'Num':
-      if (isDegenerate(node.value)) {
-        return degenerateKeyword(node.value);
-      }
-      return serializeScalar(node, prec).text;
     case 'Dim':
-      if (isDegenerate(node.value)) {
-        // Nested degenerate Dim wraps in calc() so the `<kw> * 1<unit>` form
-        // parses back as one Dim factor. The bare form round-trips wrong
-        // inside a Product — `0 * Dim(Infinity, px)` would re-fold as NaN.
-        return `calc(${degenerateKeyword(node.value)} * 1${node.rawUnit ?? node.unit})`;
-      }
-      return serializeScalar(node, prec).text;
+      emitScalar(node, session);
+      return;
     case 'Ident':
-      return node.rawName ?? node.name;
-    case 'Call': {
-      const components = getComponents(node);
-      if (components) {
-        const args = node.args
-          .map((arg) => serializeExpr(arg, prec))
-          .join(', ');
-        return `${node.rawName ?? node.name}(${args}${serializeComponents(components, (child) => serialize(child, { precision: prec }))})`;
-      }
-      const args = node.args.map((a) => serializeExpr(a, prec)).join(', ');
-      return `${node.rawName ?? node.name}(${args})`;
-    }
+      buffer.push(node.rawName ?? node.name);
+      return;
+    case 'Call':
+      emitCall(node, session);
+      return;
+    case 'OpaqueCall':
+      emitOpaqueCall(node, session);
+      return;
     case 'Sum':
-      return serializeSum(node, prec);
+      emitSum(node, session);
+      return;
     case 'Product':
-      return serializeProduct(node, prec);
+      emitProduct(node, session);
+      return;
   }
 }
 
 /**
- * Combine the term's sign with a negative Num/Dim value's sign so
- * `{sign:+1, Num(-5)}` renders as `-5`, not `+ -5`. Skip degenerate
- * (Infinity/NaN) values — the `degenerateKeyword` path emits `-infinity`
- * inline, and a leading minus on `calc(infinity*1<unit>)` would now
- * tokenize as a `-calc` function.
- * @param {{sign: 1 | -1, node: Node}} term
- * @return {{sign: 1 | -1, magnitude: Node}}
+ * @param {import('./node.js').Call} node
+ * @param {ReturnType<typeof makeContext>} session
+ * @param {string} [callNameOverride]
+ * @return {void}
  */
-function displaySign(term) {
-  const { sign, node } = term;
-  if (node.type === 'Num' && Number.isFinite(node.value) && node.value < 0) {
-    return {
-      sign: /** @type {1 | -1} */ (-sign),
-      magnitude: num(-node.value),
-    };
+function emitCall(node, session, callNameOverride) {
+  const buffer = session.buffer;
+  buffer.push(callNameOverride ?? node.rawName ?? node.name, '(');
+  for (let i = 0; i < node.args.length; i++) {
+    if (i > 0) buffer.push(', ');
+    emitNode(node.args[i], session);
   }
-  if (node.type === 'Dim' && Number.isFinite(node.value) && node.value < 0) {
-    return {
-      sign: /** @type {1 | -1} */ (-sign),
-      magnitude: dim(-node.value, node.unit, node.rawUnit),
-    };
+  buffer.push(')');
+}
+
+/**
+ * @param {import('./node.js').OpaqueCall} node
+ * @param {ReturnType<typeof makeContext>} session
+ * @param {string} [callNameOverride]
+ * @return {void}
+ */
+function emitOpaqueCall(node, session, callNameOverride) {
+  const buffer = session.buffer;
+  buffer.push(callNameOverride ?? node.rawName ?? node.name, '(');
+  serializeComponents(node.components, buffer, (child, childBuffer) => {
+    emitNestedMathResult(child, session, childBuffer);
+  });
+  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, precision) {
+  let sign = /** @type {1 | -1} */ (term.sign * multiplier);
+  if (isEffectivelyNegative(term.node, precision)) {
+    sign = /** @type {1 | -1} */ (-sign);
+  }
+  return sign;
+}
+
+/**
+ * @param {import('./node.js').SumTerm} term
+ * @param {ReturnType<typeof makeContext>} session
+ * @param {1 | -1} sign
+ * @return {void}
+ */
+function emitSumTerm(term, session, sign) {
+  if (sign === 1) {
+    emitNode(term.node, session, SUM_PRECEDENCE, true);
+  } else {
+    emitLeadingNeg(term.node, session);
   }
-  return { sign, magnitude: node };
 }
 
 /**
  * @param {import('./node.js').SumTerm[]} terms
- * @param {number | false} prec
- * @return {string}
+ * @param {ReturnType<typeof makeContext>} session
+ * @param {1 | -1} [multiplier]
+ * @return {void}
  */
-function serializeSumTerms(terms, prec) {
-  let out = '';
+function emitSumTerms(terms, session, multiplier = 1) {
+  const buffer = session.buffer;
   for (let i = 0; i < terms.length; i++) {
-    const { sign, magnitude } = displaySign(terms[i]);
-    if (i === 0) {
-      if (magnitude.type === 'Sum' && magnitude.grouped) {
-        const body = `(${serializeExpr(magnitude, prec)})`;
-        out = sign === 1 ? body : `-${body}`;
-        continue;
+    const term = terms[i];
+    const termNode = term.node;
+    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 {
+        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);
+        }
       }
-      out =
-        sign === 1
-          ? serializeExpr(magnitude, prec)
-          : serializeLeadingNeg(magnitude, prec);
+      continue;
+    }
+    const sign = /** @type {1 | -1} */ (term.sign * multiplier);
+    if (i === 0) {
+      emitSumTerm(term, session, sign);
     } else {
-      // `-` binds looser than `*`/`/` so the right side never needs parens.
-      let body = serializeExpr(magnitude, prec);
-      if (magnitude.type === 'Sum' && magnitude.grouped) {
-        body = `(${body})`;
-      }
-      out += sign === 1 ? ` + ${body}` : ` - ${body}`;
+      buffer.push(sign === 1 ? ' + ' : ' - ');
+      emitNode(termNode, session, SUM_PRECEDENCE, true);
     }
   }
-  return out;
+}
+
+/** @param {Sum} sum @param {ReturnType<typeof makeContext>} session @return {void} */
+function emitSum(sum, session) {
+  emitSumTerms(sum.terms, session);
 }
 
 /**
- * @param {Sum} sum
- * @param {number | false} prec
- * @return {string}
+ * @param {Node} node
+ * @param {ReturnType<typeof makeContext>} session
+ * @return {void}
+ */
+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('-1 * ');
+  emitNode(node, session, UNARY_PRECEDENCE, false);
+}
+
+/**
+ * @param {ProductFactor[]} factors
+ * @param {ReturnType<typeof makeContext>} session
+ * @param {number} [start]
+ * @param {number} [coefficientValue]
+ * @param {import('./node.js').Num} [coefficientNode]
+ * @return {void}
  */
-function serializeSum(sum, prec) {
-  return serializeSumTerms(sum.terms, prec);
+function emitProductFactors(
+  factors,
+  session,
+  start = 0,
+  coefficientValue,
+  coefficientNode
+) {
+  const buffer = session.buffer;
+  let first = true;
+  if (coefficientValue !== undefined && coefficientValue !== 1) {
+    emitScalar(
+      /** @type {import('./node.js').Num} */ (coefficientNode),
+      session,
+      coefficientValue
+    );
+    first = false;
+  }
+  for (let i = start; i < factors.length; i++) {
+    const factor = factors[i];
+    const factorNode = factor.node;
+    if (first) {
+      if (factor.exponent === -1) buffer.push('1 / ');
+      if (isScalar(factorNode)) emitScalar(factorNode, session);
+      else emitNode(factorNode, session, PRODUCT_PRECEDENCE);
+      first = false;
+    } else {
+      buffer.push(factor.exponent === 1 ? ' * ' : ' / ');
+      if (isScalar(factorNode)) emitScalar(factorNode, session);
+      else emitNode(factorNode, session, PRODUCT_PRECEDENCE);
+    }
+  }
+}
+
+/** @param {Product} product @param {ReturnType<typeof makeContext>} session @return {void} */
+function emitProduct(product, session) {
+  emitProductFactors(product.factors, session);
+}
+
+/** @param {Node} node @param {ReturnType<typeof makeContext>} session @return {void} */
+function emitRootExpr(node, session) {
+  if (
+    node.type === 'Sum' &&
+    node.grouped &&
+    node.terms.length > 1 &&
+    termSign(node.terms[0], 1, session.precision) === -1
+  ) {
+    session.buffer.push('-1 * (');
+    emitSumTerms(node.terms, session, -1);
+    session.buffer.push(')');
+    return;
+  }
+  if (node.type === 'Sum' && node.terms.length === 1) {
+    emitLeadingNeg(node.terms[0].node, session);
+    return;
+  }
+  emitNode(node, session);
 }
 
 /**
- * Fold a leading negation into a finite leading Num if there is one
- * (`-(0.5 * x)` → `-0.5 * x`); else use `-(…)` for Sum/Product or `-x`.
  * @param {Node} node
- * @param {number | false} prec
- * @return {string}
+ * @param {ReturnType<typeof makeContext>} session
+ * @param {string} wrapper
+ * @return {void}
  */
-function serializeLeadingNeg(node, prec) {
+function emitMathResult(node, session, wrapper) {
+  if (isScalar(node)) {
+    const scalarValue = roundedScalarValue(node, session.precision);
+    const buffer = session.buffer;
+    if (isDegenerate(scalarValue)) {
+      buffer.push(wrapper, '(', degenerateKeyword(scalarValue));
+      if (node.type === 'Dim') buffer.push(' * 1', node.rawUnit ?? node.unit);
+      buffer.push(')');
+    } else if (session.scalarPolicy === 'standard') {
+      buffer.push(wrapper, '(');
+      emitRoundedScalar(node, buffer, scalarValue);
+      buffer.push(')');
+    } else {
+      emitRoundedScalar(node, buffer, scalarValue);
+    }
+    return;
+  }
   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
+    node.type === 'Sum' &&
+    node.grouped &&
+    node.terms.length > 1 &&
+    termSign(node.terms[0], 1, session.precision) === -1
   ) {
-    const head = node.factors[0].node;
-    const negatedValue = -head.value;
-    const rest = node.factors.slice(1);
-    // A coefficient of 1 is a no-op factor, matching mkProduct.
-    /** @type {ProductFactor[]} */
-    const negatedFactors =
-      negatedValue === 1
-        ? rest
-        : [{ exponent: 1, node: num(negatedValue) }, ...rest];
-    return serializeFactors(negatedFactors, prec);
+    session.buffer.push(wrapper, '(-1 * (');
+    emitSumTerms(node.terms, session, -1);
+    session.buffer.push('))');
+    return;
   }
-  const body = serializeExpr(node, prec);
-  return node.type === 'Sum' || node.type === 'Product'
-    ? `-(${body})`
-    : `-${body}`;
+  if (
+    node.type === 'Ident' ||
+    node.type === 'Call' ||
+    node.type === 'OpaqueCall'
+  ) {
+    emitNode(node, session);
+    return;
+  }
+  if (node.type === 'Sum' && node.terms.length === 1) {
+    session.buffer.push(wrapper, '(');
+    emitLeadingNeg(node.terms[0].node, session);
+    session.buffer.push(')');
+    return;
+  }
+  session.buffer.push(wrapper, '(');
+  emitNode(node, session);
+  session.buffer.push(')');
 }
 
 /**
- * @param {ProductFactor[]} factors
- * @param {number | false} prec
+ * Serialize a scalar result without allocating a render context or buffer.
+ * @param {import('./node.js').Num | import('./node.js').Dim} node
+ * @param {number | false} precision
+ * @param {'standard' | 'unwrap-all'} scalarPolicy
+ * @param {string} wrapper
  * @return {string}
  */
-function serializeFactors(factors, prec) {
-  let out = '';
-  for (let i = 0; i < factors.length; i++) {
-    const f = factors[i];
-    let body = serializeExpr(f.node, prec);
-    // A Sum factor needs parens: `a * (b + c)`. Flat canonical form means
-    // this is the only place parens are required.
-    if (f.node.type === 'Sum') {
-      body = `(${body})`;
+function serializeScalarResult(node, precision, scalarPolicy, wrapper) {
+  const value = roundedScalarValue(node, precision);
+  const unit = node.type === 'Dim' ? (node.rawUnit ?? node.unit) : '';
+  if (isDegenerate(value)) {
+    return `${wrapper}(${degenerateKeyword(value)}${unit ? ` * 1${unit}` : ''})`;
+  }
+  const scalar = serializeNumber(value) + unit;
+  return scalarPolicy === 'standard' ? `${wrapper}(${scalar})` : scalar;
+}
+
+/**
+ * @param {Node} node
+ * @param {ReturnType<typeof makeContext>} session
+ * @param {string[]} [buffer]
+ * @return {void}
+ */
+function emitNestedMathResult(node, session, buffer = session.buffer) {
+  if (isSignedZero(node)) {
+    emitSignedZero(buffer, node);
+    return;
+  }
+  emitMathResult(node, session, 'calc');
+}
+
+/**
+ * @param {SerializeOptions} opts
+ * @return {{buffer: string[], precision: number | false, scalarPolicy: 'standard' | 'unwrap-all'}}
+ */
+function makeContext(opts) {
+  return {
+    buffer: [],
+    precision: opts.precision ?? 5,
+    scalarPolicy: normalizeScalarPolicy(opts),
+  };
+}
+
+/**
+ * @param {Node} node
+ * @param {SerializeOptions} opts
+ * @return {{kind: 'math', node: Node, session: ReturnType<typeof makeContext>, wrapper: string}}
+ */
+function planSerialize(node, opts) {
+  return {
+    kind: 'math',
+    node,
+    session: makeContext(opts),
+    wrapper: opts.calcName ?? 'calc',
+  };
+}
+
+/**
+ * @param {{tree: Node, status: 'resolved' | 'unresolved', rootName: string, rootSpelling: string, calculation?: boolean, original?: string}} result
+ * @param {SerializeOptions} opts
+ * @return {{kind: 'original', text: string} | {kind: 'root-call', node: Node, session: ReturnType<typeof makeContext>, callNameOverride: string} | {kind: 'wrapped-expr', node: Node, session: ReturnType<typeof makeContext>, wrapper: string} | {kind: 'math', node: Node, session: ReturnType<typeof makeContext>, wrapper: string}}
+ */
+function planSerializeResult(result, opts) {
+  const isCalc = result.calculation ?? isCalculationFunction(result.rootName);
+  const normalizedRootName =
+    result.calculation === undefined
+      ? result.rootName.toLowerCase()
+      : result.rootName;
+  const wrapper = isCalc
+    ? result.rootSpelling || opts.calcName || 'calc'
+    : 'calc';
+  const session = makeContext(opts);
+
+  if (!isCalc && result.status === 'unresolved') {
+    if (
+      (result.tree.type === 'Call' || result.tree.type === 'OpaqueCall') &&
+      result.tree.name.toLowerCase() === normalizedRootName
+    ) {
+      return {
+        kind: 'root-call',
+        node: result.tree,
+        session,
+        callNameOverride: result.rootSpelling,
+      };
     }
-    if (i === 0) {
-      // Leading denominator: implicit 1 so we emit `1 / 2px`, not `/ 2px`.
-      out = f.exponent === 1 ? body : `1 / ${body}`;
+    return { kind: 'original', text: result.original ?? '' };
+  }
+
+  if (session.scalarPolicy === 'standard') {
+    if (isScalar(result.tree))
+      return { kind: 'math', node: result.tree, session, wrapper };
+    return { kind: 'wrapped-expr', node: result.tree, session, wrapper };
+  }
+  return { kind: 'math', node: result.tree, session, wrapper };
+}
+
+/**
+ * @param {ReturnType<typeof planSerialize> | ReturnType<typeof planSerializeResult>} renderSpec
+ * @return {string}
+ * */
+function emitOutput(renderSpec) {
+  if (renderSpec.kind === 'original') return renderSpec.text;
+  const { session } = renderSpec;
+  if (renderSpec.kind === 'root-call') {
+    if (renderSpec.node.type === 'Call') {
+      emitCall(renderSpec.node, session, renderSpec.callNameOverride);
     } else {
-      out += f.exponent === 1 ? ` * ${body}` : ` / ${body}`;
+      emitOpaqueCall(
+        /** @type {import('./node.js').OpaqueCall} */ (renderSpec.node),
+        session,
+        renderSpec.callNameOverride
+      );
     }
+  } else if (renderSpec.kind === 'wrapped-expr') {
+    session.buffer.push(renderSpec.wrapper, '(');
+    emitRootExpr(renderSpec.node, session);
+    session.buffer.push(')');
+  } else {
+    emitMathResult(renderSpec.node, session, renderSpec.wrapper);
   }
-  return out;
+  return session.buffer.join('');
 }
 
 /**
- * @param {Product} product
- * @param {number | false} prec
+ * @param {Node} node
+ * @param {SerializeOptions} [opts]
+ * @return {string}
+ */
+function serialize(node, opts = {}) {
+  if (isScalar(node)) {
+    return serializeScalarResult(
+      node,
+      opts.precision ?? 5,
+      normalizeScalarPolicy(opts),
+      opts.calcName ?? 'calc'
+    );
+  }
+  checkCalculationDepth(node);
+  return emitOutput(planSerialize(node, opts));
+}
+
+/**
+ * @param {{tree: Node, status: 'resolved' | 'unresolved', rootName: string, rootSpelling: string, calculation?: boolean, original?: string}} result
+ * @param {SerializeOptions} [opts]
  * @return {string}
  */
-function serializeProduct(product, prec) {
-  return serializeFactors(product.factors, prec);
+function serializeResult(result, opts = {}) {
+  const node = result.tree;
+  if (isScalar(node)) {
+    const isCalc = result.calculation ?? isCalculationFunction(result.rootName);
+    if (!isCalc && result.status === 'unresolved') return result.original ?? '';
+    const wrapper = isCalc
+      ? result.rootSpelling || opts.calcName || 'calc'
+      : 'calc';
+    return serializeScalarResult(
+      node,
+      opts.precision ?? 5,
+      normalizeScalarPolicy(opts),
+      wrapper
+    );
+  }
+  checkCalculationDepth(result.tree);
+  return emitOutput(planSerializeResult(result, opts));
 }
 
-export { serialize };
+export { serialize, serializeResult };