@cortex-js/compute-engine 0.57.0 → 0.59.0

package/dist/types/compute-engine/types-expression.d.ts

@@ -1,4 +1,4 @@
-/* 0.57.0 */
+/* 0.59.0 */
 import type { OneOf } from '../common/one-of';
 import type { MathJsonExpression, MathJsonNumberObject, MathJsonStringObject, MathJsonSymbolObject, MathJsonFunctionObject, MathJsonSymbol, MathJsonDictionaryObject } from '../math-json';
 import type { Type, TypeString } from '../common/type/types';
@@ -405,6 +405,20 @@ export interface Tensor<DT extends TensorDataType> extends TensorData<DT> {
  * @category Boxed Expression
  *
  */
+/**
+ * Lower and upper bounds for a symbol extracted from a domain restriction.
+ *
+ * `lowerStrict`/`upperStrict` are `true` for strict (`<`, `>`) bounds and
+ * `false` (or `undefined`) for non-strict (`≤`, `≥`) bounds.
+ *
+ * @category Boxed Expression
+ */
+export type IntervalBounds = {
+    lower?: Expression;
+    lowerStrict?: boolean;
+    upper?: Expression;
+    upperStrict?: boolean;
+};
 export interface Expression {
     /** @internal */
     readonly _kind: string;
@@ -1051,26 +1065,29 @@ export interface Expression {
      *
      * - If no rules apply, return `null`.
      *
-     * See also `expr.subs()` for a simple substitution of symbols.
-     *
-     * Procedure for the determining the canonical-status of the input expression and replacements:
+     * The `form` option controls the form of *replacements*. The deprecated
+     * `canonical` option is also accepted for backward compatibility; only one
+     * of the two may be specified.
      *
-     * - If `options.canonical` is set, the *entire expr.* is canonicalized to this degree: whether
-     * the replacement occurs at the top-level, or within/recursively.
+     * When neither `form` nor `canonical` is specified, the form of each
+     * replacement is determined as follows:
+     * 1. the form of the replacement produced by the rule, if it has a
+     *    non-`'raw'` form;
+     * 2. otherwise, the form of the expression being replaced;
+     * 3. otherwise, the replacement is left in its raw form.
      *
-     * - If otherwise, the *direct replacement will be canonical* if either the 'replaced' expression
-     * is canonical, or the given replacement (- is a Expression and -) is canonical.
-     * Notably also, if this replacement takes place recursively (not at the top-level), then exprs.
-     * containing the replaced expr. will still however have their (previous) canonical-status
-     * *preserved*... unless this expr. was previously non-canonical, and *replacements have resulted
-     * in canonical operands*. In this case, an expr. meeting this criteria will be updated to
-     * canonical status. (Canonicalization is opportunistic here, in other words).
+     * While the form applies directly to replaced sub-expressions only, a
+     * non-`'raw'` form also propagates 'opportunistically' up the expression
+     * tree: an expression whose operands all share a form after replacement
+     * assumes that form as well. (Specifying `form: 'raw'` disables this
+     * propagation.)
      *
      * :::info[Note]
-     * Applicable to canonical and non-canonical expressions.
+     * Applicable to input expressions of any form.
      *
      * To match a specific symbol (not a wildcard pattern), the `match` must be
      * a `Expression` (e.g., `{ match: ce.expr('x'), replace: ... }`).
+     *
      * For simple symbol substitution, consider using `subs()` instead.
      * :::
      */
@@ -1372,6 +1389,60 @@ export interface Expression {
      *
      */
     simplify(options?: Partial<SimplifyOptions>): Expression;
+    /**
+     * For a relation expression (`Equal`, `Less`, `Greater`, `LessEqual`,
+     * `GreaterEqual`, `NotEqual`), return the "signed function" form
+     * useful for implicit-surface rendering and region classification:
+     *
+     * - `Equal(a, b)` → `a - b` (zero on the surface)
+     * - `Less(a, b)` / `LessEqual(a, b)` → `a - b` (negative when relation holds)
+     * - `Greater(a, b)` / `GreaterEqual(a, b)` → `b - a` (negative when relation holds)
+     * - `NotEqual(a, b)` → `a - b` (caller checks ≠ 0)
+     *
+     * For non-relation expressions, returns `undefined`.
+     *
+     * Strictness (strict vs non-strict inequality) and direction (less vs
+     * greater) are encoded in the original `expr.operator`, not in the
+     * returned expression. Callers handling 3D implicit rendering use
+     * `expr.operator` for the boundary policy and the signed function for
+     * the interior/exterior classification.
+     *
+     * Notes:
+     * - CE canonical form normalizes `GreaterEqual(a, b)` to `LessEqual(b, a)`
+     *   (and similarly `Greater` to `Less`). Callers using `toSignedFunction()`
+     *   on canonicalized parsed expressions will see `LessEqual`/`Less` rather
+     *   than `GreaterEqual`/`Greater`. The signed-function semantics are
+     *   preserved through the normalization. The `GreaterEqual`/`Greater`
+     *   branches handle non-canonical expressions constructed via
+     *   `ce.box(['GreaterEqual', ...])`.
+     * - For chained relations with more than two operands (e.g.
+     *   `Less(a, b, c)` from `a < b < c`), only the first pair is used.
+     *   The result is the signed function for the first sub-relation only;
+     *   3D implicit rendering rarely uses chained relations, but if it
+     *   does, callers should decompose first.
+     */
+    toSignedFunction(): BoxedExpression | undefined;
+    /**
+     * For an expression representing a domain restriction (a `When` whose
+     * condition is a comparison or `And` of comparisons over `symbol`, or
+     * a bare comparison expression), return the lower/upper bounds for
+     * `symbol`. Returns `undefined` if no bounds can be extracted.
+     *
+     * Supported shapes:
+     * - Bare comparisons: `a < x`, `x < b`, etc.
+     * - Chained comparisons: `a < x < b` (parsed as `Less(a, x, b)`)
+     * - `And(c1, c2, ...)` where each `ci` is a supported shape
+     * - `When(e, cond)` — operates on `cond`
+     * - `Multiply(f, When(...), ...)` — the Desmos parse shape for
+     *   `f(x)\{a < x < b\}`; bounds from each `When` factor are merged
+     *
+     * `lowerStrict`/`upperStrict` are `true` for strict (`<`, `>`) bounds
+     * and `false` for non-strict (`≤`, `≥`).
+     *
+     * Returns `undefined` for unsupported shapes (e.g. equations, non-linear
+     * constraints, comparisons over multiple symbols, disjunctions).
+     */
+    getInterval(symbol: string): IntervalBounds | undefined;
     /**
      * Return the value of the canonical form of this expression.
      *

package/dist/types/compute-engine/types-kernel-evaluation.d.ts

@@ -1,4 +1,4 @@
-/* 0.57.0 */
+/* 0.59.0 */
 import type { TypeReference } from '../common/type/types';
 import type { BoxedType } from '../common/type/boxed-type';
 import type { LatexString } from './latex-syntax/types';
@@ -80,10 +80,27 @@ export type RuleReplaceFunction<Expr = unknown> = (expr: Expr, wildcards: BoxedS
 export type RuleConditionFunction<Expr = unknown, CE = unknown> = (wildcards: BoxedSubstitution<Expr>, ce: CE) => boolean;
 /** @category Rules */
 export type RuleFunction<Expr = unknown> = (expr: Expr) => undefined | Expr | RuleStep<Expr>;
+/**
+ * The purpose of a rule determines how its result is treated by
+ * the simplification cost policy:
+ *
+ * - `'simplify'`: the result must pass the cost gate (the default;
+ *   today's behavior — results that grow the expression are discarded).
+ * - `'transform'`: a mathematically-preferred rewrite; exempt from the
+ *   cost gate (accepted by `simplify()` even if structurally larger).
+ * - `'expand'`: growth-by-design (series, argument expansion); skipped by
+ *   `simplify()`, but reachable via `expr.replace()` and future expand APIs.
+ *
+ * @category Rules
+ */
+export type RulePurpose = 'simplify' | 'transform' | 'expand';
 /** @category Rules */
 export type RuleStep<Expr = unknown> = {
     value: Expr;
     because: string;
+    /** The purpose of the rule that produced this step, stamped by
+     * `applyRule` from the firing rule. */
+    purpose?: RulePurpose;
 };
 /** @category Rules */
 export type RuleSteps<Expr = unknown> = RuleStep<Expr>[];
@@ -117,6 +134,13 @@ export type Rule<Expr = unknown, SemiExpr = unknown, CE = unknown> = string | Ru
     replace: LatexString | SemiExpr | RuleReplaceFunction<Expr> | RuleFunction<Expr>;
     condition?: LatexString | RuleConditionFunction<Expr, CE>;
     useVariations?: boolean;
+    /** Dispatch hint: this rule can only ever apply to expressions whose
+     *  operator is one of these. Used to index the rule; semantics are
+     *  unchanged (the rule is simply never tried on other operators). */
+    operators?: ReadonlyArray<string>;
+    /** How the result of this rule is treated by the simplification cost
+     *  policy. See {@linkcode RulePurpose}. **Default**: `'simplify'`. */
+    purpose?: RulePurpose;
     id?: string;
     onBeforeMatch?: (rule: Rule<Expr, SemiExpr, CE>, expr: Expr) => void;
     onMatch?: (rule: Rule<Expr, SemiExpr, CE>, expr: Expr, replace: Expr | RuleStep<Expr>) => void;
@@ -128,6 +152,13 @@ export type BoxedRule<Expr = unknown, CE = unknown> = {
     replace: Expr | RuleReplaceFunction<Expr> | RuleFunction<Expr>;
     condition: undefined | RuleConditionFunction<Expr, CE>;
     useVariations?: boolean;
+    /** Dispatch hint: this rule can only ever apply to expressions whose
+     *  operator is one of these. Used to index the rule; semantics are
+     *  unchanged (the rule is simply never tried on other operators). */
+    operators?: ReadonlyArray<string>;
+    /** How the result of this rule is treated by the simplification cost
+     *  policy. See {@linkcode RulePurpose}. **Default**: `'simplify'`. */
+    purpose?: RulePurpose;
     id?: string;
     onBeforeMatch?: (rule: Rule<Expr, unknown, CE>, expr: Expr) => void;
     onMatch?: (rule: Rule<Expr, unknown, CE>, expr: Expr, replace: Expr | RuleStep<Expr>) => void;

package/dist/types/compute-engine/types-kernel-serialization.d.ts

@@ -1,4 +1,4 @@
-/* 0.57.0 */
+/* 0.59.0 */
 export type Hold = 'none' | 'all' | 'first' | 'rest' | 'last' | 'most';
 /**
  * Options to control serialization to MathJSON when using
@@ -126,9 +126,51 @@ export type ReplaceOptions = {
      */
     iterationLimit: number;
     /**
-     * Canonicalization policy after replacement.
+     * Canonical-status of replaced sub-expressions.
+     *
+     * Equivalent to `form`: `true` maps to `'canonical'`, `false` to `'raw'`,
+     * and a `CanonicalForm` (or array of them) is used as-is. Specifying both
+     * `canonical` and `form` is an error.
+     *
+     * @deprecated Use `form` instead, which covers a wider range of forms.
+     */
+    canonical?: CanonicalOptions;
+    /**
+     * The form (`'canonical'`, `'structural'`, `'raw'`, or specific canonical
+     * transforms) applied to *replaced* sub-expressions.
+     *
+     * The form does not automatically apply to the entire input expression.
+     * However, a non-`'raw'` form propagates upward through the expression tree:
+     * an expression whose operands all share a form after replacement assumes
+     * that form as well.
+     *
+     * To guarantee a form for the *entire* result, either ensure the input is
+     * already in the requested form before replacing, or request the form on the
+     * result after replacement (e.g. with `.canonical`).
+     *
+     * If no `form` (or `canonical`) option is specified, the form of each
+     * replacement is determined by the rule itself: see `replace()`.
+     *
+     * Note: a `'raw'` form does not undo a form the replacement already has,
+     * e.g. when a `RuleFunction` returns an expression that is already
+     * canonical.
+     */
+    form: FormOption;
+    /**
+     * Traversal direction through the expression tree, for both rule matching
+     * and replacement:
+     *
+     * - `'left-right'` (default): post-order traversal — left sub-tree first,
+     *   depth-first (LRN).
+     * - `'right-left'`: reverse post-order — right sub-tree first, depth-first
+     *   (RLN).
+     *
+     * In both cases the root (input) expression is visited last.
+     *
+     * The direction is only observable for order-sensitive rules, e.g. a
+     * `RuleFunction` whose replacements depend on visit order.
      */
-    canonical: CanonicalOptions;
+    direction: 'left-right' | 'right-left';
 };
 /**
  * Canonical normalization transforms.

package/dist/types/compute-engine/types-serialization.d.ts

@@ -1,4 +1,4 @@
-/* 0.57.0 */
+/* 0.59.0 */
 import type { BoxedSubstitution as KernelBoxedSubstitution, CanonicalForm, CanonicalOptions, FormOption, Hold, JsonSerializationOptions, Metadata, PatternMatchOptions as KernelPatternMatchOptions, ReplaceOptions, Substitution as KernelSubstitution } from './types-kernel-serialization';
 export type { Hold, JsonSerializationOptions, ReplaceOptions, CanonicalForm, CanonicalOptions, FormOption, Metadata, };
 /**

package/dist/types/compute-engine/types.d.ts

@@ -1,4 +1,4 @@
-/* 0.57.0 */
+/* 0.59.0 */
 export type { MathJsonExpression, MathJsonAttributes, MathJsonNumberObject, MathJsonSymbolObject, MathJsonStringObject, MathJsonFunctionObject, DictionaryValue, MathJsonDictionaryObject, ExpressionObject, MathJsonSymbol, } from '../math-json/types';
 export * from '../common/type/boxed-type';
 export * from '../common/type/types';

package/dist/types/compute-engine.d.ts

@@ -1,4 +1,4 @@
-/* 0.57.0 */
+/* 0.59.0 */
 export { ComputeEngine } from './compute-engine/index';
 export type * from './compute-engine/types';
 export { LatexSyntax, parse as parseLatex, serialize as serializeLatex, } from './compute-engine/latex-syntax/latex-syntax';

package/dist/types/core.d.ts

@@ -1,4 +1,4 @@
-/* 0.57.0 */
+/* 0.59.0 */
 export { ComputeEngine } from './compute-engine/index';
 export type * from './compute-engine/types';
 export type { Interval, IntervalResult, BoolInterval, } from './compute-engine/interval/types';

package/dist/types/identities.d.ts

@@ -0,0 +1,3 @@
+/* 0.59.0 */
+export { loadIdentities, FUNGRIM_CORE } from './compute-engine/fungrim/loader';
+export type { IdentitiesLoadOptions, IdentitiesLoadReport, IdentitiesRuleData, IdentitiesGuardUndecidedHandler, FungrimLoadOptions, FungrimLoadReport, FungrimRuleData, FungrimGuardUndecidedHandler, FungrimManifest, FungrimShellDeclaration, FungrimRuleClass, FungrimRuleTarget, FungrimMathJson, CompiledFungrimRule, GuardSpec, } from './compute-engine/fungrim/types';

package/dist/types/interval.d.ts

@@ -1,4 +1,4 @@
-/* 0.57.0 */
+/* 0.59.0 */
 export type { Interval, IntervalResult, BoolInterval, } from './compute-engine/interval/types';
 export { ok, point, containsExtremum, unionResults, mergeDomainClip, isPoint, containsZero, isPositive, isNegative, isNonNegative, isNonPositive, width, midpoint, getValue, unwrap, unwrapOrPropagate, } from './compute-engine/interval/util';
 export { add, sub, mul, div, negate, _mul, } from './compute-engine/interval/arithmetic';

package/dist/types/latex-syntax.d.ts

@@ -1,4 +1,4 @@
-/* 0.57.0 */
+/* 0.59.0 */
  * Entry point for `@cortex-js/compute-engine/latex-syntax`.
  *
  * Provides standalone LaTeX <-> MathJSON parsing and serialization
@@ -11,4 +11,4 @@ export type { LatexSyntaxOptions } from './compute-engine/latex-syntax/latex-syn
 export { LATEX_DICTIONARY, CORE_DICTIONARY, SYMBOLS_DICTIONARY, ALGEBRA_DICTIONARY, ARITHMETIC_DICTIONARY, COMPLEX_DICTIONARY, TRIGONOMETRY_DICTIONARY, CALCULUS_DICTIONARY, LINEAR_ALGEBRA_DICTIONARY, STATISTICS_DICTIONARY, LOGIC_DICTIONARY, SETS_DICTIONARY, INEQUALITIES_DICTIONARY, UNITS_DICTIONARY, OTHERS_DICTIONARY, PHYSICS_DICTIONARY, } from './compute-engine/latex-syntax/dictionary/default-dictionary';
 export type { LatexDictionaryEntry, LatexDictionary, SerializeLatexOptions, ParseLatexOptions, LatexString, } from './compute-engine/latex-syntax/types';
 export type { MathJsonExpression } from './math-json/types';
-export declare const version = "0.57.0";
+export declare const version = "0.59.0";

package/dist/types/math-json/symbols.d.ts

@@ -1,4 +1,4 @@
-/* 0.57.0 */
+/* 0.59.0 */
  * Return true if the string is a valid symbol.
  *
  * Check for symbols matching a profile of [Unicode UAX31](https://unicode.org/reports/tr31/)

package/dist/types/math-json/types.d.ts

@@ -1,4 +1,4 @@
-/* 0.57.0 */
+/* 0.59.0 */
  * The following properties can be added to any MathJSON expression
  * to provide additional information about the expression.
  *

package/dist/types/math-json/utils.d.ts

@@ -1,4 +1,4 @@
-/* 0.57.0 */
+/* 0.59.0 */
 export declare const MISSING: MathJsonExpression;
 export declare function isNumberExpression(expr: MathJsonExpression | null): expr is number | string | MathJsonNumberObject;
 export declare function isNumberObject(expr: MathJsonExpression | null): expr is MathJsonNumberObject;

package/dist/types/math-json.d.ts

@@ -1,3 +1,3 @@
-/* 0.57.0 */
+/* 0.59.0 */
 export { isSymbolObject, isStringObject, isFunctionObject, stringValue, operator, operand, symbol, mapArgs, dictionaryFromExpression, } from './math-json/utils';
-export declare const version = "0.57.0";
+export declare const version = "0.59.0";

package/dist/types/numerics.d.ts

@@ -1,4 +1,4 @@
-/* 0.57.0 */
+/* 0.59.0 */
 export type { SmallInteger, Rational, BigNum, } from './compute-engine/numerics/types';
 export type { ExactNumericValueData, NumericValueData, NumericValueFactory, } from './compute-engine/numeric-value/types';
 export { NumericValue } from './compute-engine/numeric-value/types';

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.57.0",
+  "version": "0.59.0",
   "scripts": {
     "doc": "bash ./scripts/doc.sh",
     "build": "bash ./scripts/build.sh",
@@ -84,6 +84,12 @@
       "import": "./dist/compile.min.esm.js",
       "require": "./dist/compile.min.umd.cjs",
       "default": "./dist/compile.min.esm.js"
+    },
+    "./identities": {
+      "types": "./dist/types/identities.d.ts",
+      "import": "./dist/identities.min.esm.js",
+      "require": "./dist/identities.min.umd.cjs",
+      "default": "./dist/identities.min.esm.js"
     }
   },
   "main": "./dist/compute-engine.min.esm.js",
@@ -106,6 +112,7 @@
     "chalk": "^5.6.2",
     "check-node-version": "^4.2.1",
     "concat-md": "^0.5.1",
+    "decimal.js": "^10.6.0",
     "esbuild": "^0.27.3",
     "eslint": "^8.56.0",
     "eslint-config-prettier": "^10.1.8",
@@ -130,7 +137,6 @@
   "prettier": "@cortex-js/prettier-config",
   "dependencies": {
     "@arnog/colors": "^0.5.0",
-    "complex-esm": "^2.1.1-esm1",
-    "decimal.js": "^10.6.0"
+    "complex-esm": "^2.1.1-esm1"
   }
 }