arch: free functions

Author: arnog

README.md

@@ -26,87 +26,38 @@ $ npm install --save @cortex-js/compute-engine
 
 ### Basic Parsing and Evaluation
 
-```js
-import { ComputeEngine } from "@cortex-js/compute-engine";
-
-const ce = new ComputeEngine();
-
-// Parse LaTeX and evaluate
-const result = ce.parse("2^{11}-1").evaluate();
-console.log(result.toString());
-// ➔ 2047
-
-// Check properties
-ce.parse("2^{11}-1 \\in \\Z").evaluate().print();
-// ➔ True
-```
-
-### Workflow Helpers (Parse + Transform)
-
-For common app flows, you can use the high-level workflow helpers:
+No setup required:
 
 ```js
-import { ComputeEngine } from "@cortex-js/compute-engine";
+import { parse, simplify, evaluate, N, assign } from "@cortex-js/compute-engine";
 
-const ce = new ComputeEngine();
-
-// Parse then simplify
-ce.parseSimplify("x + x + 1").print();
+simplify("x + x + 1").print();
 // ➔ 2x + 1
 
-// Select simplification strategy presets
-ce.parseSimplify("2\\sin(x)\\cos(x)", { simplifyMode: "trigonometric" }).print();
-// ➔ sin(2x)
-
-// Parse then evaluate (using current context)
-ce.assign("x", 3);
-ce.parseEvaluate("x + 2").print();
-// ➔ 5
+evaluate("2^{11} - 1").print();
+// ➔ 2047
 
-// Parse then compute numeric approximation
-ce.parseNumeric("\\sqrt{2}").print();
+N("\\sqrt{2}").print();
 // ➔ 1.414213562...
 
-// Use permissive parsing for plain function names such as sin(x)
-ce.parseSimplify("sin(x)", { parseMode: "permissive" }).print();
-// ➔ sin(x)
-
-// Choose exact or numeric evaluation behavior
-ce.parseEvaluate("\\sqrt{2}", { evaluateMode: "exact" }).print();
-// ➔ sqrt(2)
-ce.parseEvaluate("\\sqrt{2}", { evaluateMode: "numeric" }).print();
-// ➔ 1.414213562...
+assign("x", 3);
+evaluate("x + 2").print();
+// ➔ 5
 ```
 
-These methods return `null` when the input LaTeX is `null`.
-When both a preset and explicit options are provided, explicit `parse`/`evaluate`
-options take precedence. Likewise, explicit `simplify.strategy` takes precedence
-over `simplifyMode`.
-
-### Extension Contracts
-
-Plugin-facing extension points now enforce runtime contracts:
-
-- `ce.registerCompilationTarget(name, target)` validates target names and
-  required `LanguageTarget` methods (`getOperators()`, `getFunctions()`,
-  `createTarget()`, `compile()`).
-- Custom libraries passed with `new ComputeEngine({ libraries: [...] })` are
-  validated for `name`, `requires`, `definitions`, and `latexDictionary` shape.
-- Rule replacement callbacks must return a boxed expression or a valid rule step.
-
-Architecture snapshot: [docs/architecture/CURRENT-ARCHITECTURE.md](docs/architecture/CURRENT-ARCHITECTURE.md)
+These functions use a shared `ComputeEngine` instance created on first use. Use
+`getDefaultEngine()` to configure it, or create your own instance for isolated
+configurations.
 
 ### Working with Numbers (Type-Safe)
 
 Use type guards to safely access specialized properties:
 
 ```js
-import { ComputeEngine, isBoxedNumber } from "@cortex-js/compute-engine";
+import { evaluate, isBoxedNumber } from "@cortex-js/compute-engine";
 
-const ce = new ComputeEngine();
-const expr = ce.parse("\\frac{5}{2}").evaluate();
+const expr = evaluate("\\frac{5}{2}");
 
-// ✓ Modern approach with type guards
 if (isBoxedNumber(expr)) {
   console.log(expr.numericValue);  // 2.5 (type-safe access)
   console.log(expr.isInteger);     // false
@@ -116,18 +67,17 @@ if (isBoxedNumber(expr)) {
 ### Working with Symbols
 
 ```js
-import { ComputeEngine, isBoxedSymbol, sym } from "@cortex-js/compute-engine";
+import { parse, isBoxedSymbol, sym } from "@cortex-js/compute-engine";
 
-const ce = new ComputeEngine();
-const expr = ce.parse("x + 1");
+const expr = parse("x + 1");
 
 // Check if expression is a specific symbol
 if (sym(expr) === "x") {
   console.log("This is the variable x");
 }
 
 // Or use full type guard for more access
-const variable = ce.parse("y");
+const variable = parse("y");
 if (isBoxedSymbol(variable)) {
   console.log(variable.symbol);  // "y"
 }
@@ -136,10 +86,9 @@ if (isBoxedSymbol(variable)) {
 ### Working with Functions
 
 ```js
-import { ComputeEngine, isBoxedFunction } from "@cortex-js/compute-engine";
+import { parse, isBoxedFunction } from "@cortex-js/compute-engine";
 
-const ce = new ComputeEngine();
-const expr = ce.parse("2x + 3y");
+const expr = parse("2x + 3y");
 
 // Access function structure safely
 if (isBoxedFunction(expr)) {
@@ -156,44 +105,44 @@ if (isBoxedFunction(expr)) {
 ### Simplification and Manipulation
 
 ```js
-import { ComputeEngine, expand } from "@cortex-js/compute-engine";
+import { parse, simplify, expand } from "@cortex-js/compute-engine";
 
-const ce = new ComputeEngine();
 
 // Simplify expressions
-ce.parse("x + x").simplify().print();
+simplify("x + x").print();
 // ➔ 2x
 
 // Expand expressions (free function)
-const expr = ce.parse("(x + 1)^2");
+const expr = parse("(x + 1)^2");
 expand(expr).print();
 // ➔ x^2 + 2x + 1
 
 // Substitute values
-const expr2 = ce.parse("x^2 + 2x + 1");
+const expr2 = parse("x^2 + 2x + 1");
 expr2.subs({ x: 3 }).evaluate().print();
 // ➔ 16
 ```
 
 ### Solving Equations
 
 ```js
-const ce = new ComputeEngine();
 
 // Solve linear system
-const system = ce.parse("\\begin{cases}x+y=5\\\\x-y=1\\end{cases}");
+const system = parse("\\begin{cases}x+y=5\\\\x-y=1\\end{cases}");
 const solution = system.solve(["x", "y"]);
 
 console.log(solution.x.json);  // 3
 console.log(solution.y.json);  // 2
 ```
 
 **💡 Best Practices:**
-- Always use type guards (`isBoxedNumber`, `isBoxedSymbol`, `isBoxedFunction`) before accessing specialized properties
-- Import type guards from `@cortex-js/compute-engine` alongside `ComputeEngine`
+
+- Always use type guards (`isBoxedNumber`, `isBoxedSymbol`, `isBoxedFunction`)
+  before accessing specialized properties
 - Use the `sym()` helper for quick symbol name checks
 
-**📚 Learn More:** [Full documentation and guides](https://cortexjs.io/compute-engine/)
+**📚 Learn More:**
+[Full documentation and guides](https://cortexjs.io/compute-engine/)
 
 ## FAQ
 

docs/README.md

@@ -0,0 +1,56 @@
+# Compute Engine Docs Guide
+
+This directory contains both user-facing guides and internal engineering
+snapshots.
+
+## Start Here
+
+For installation, quick-start examples, and the main public API entrypoints,
+read the repository [`README.md`](../README.md).
+
+## Documentation Map
+
+| Goal | Recommended doc |
+| --- | --- |
+| Learn package usage quickly | [`../README.md`](../README.md) |
+| Use parse-and-transform helper methods | This file (Workflow Helpers section) |
+| Understand simplification behavior snapshots | [`SIMPLIFY.md`](./SIMPLIFY.md), [`SIMPLIFICATIONS.md`](./SIMPLIFICATIONS.md) |
+| Review playground sample outcomes | [`PLAYGROUND.md`](./PLAYGROUND.md) |
+| Review internal architecture boundaries | [`architecture/README.md`](./architecture/README.md) |
+
+## Workflow Helpers
+
+High-level workflow entrypoints:
+
+- `ce.parseSimplify(latex, options?)`
+- `ce.parseEvaluate(latex, options?)`
+- `ce.parseNumeric(latex, options?)`
+
+Policy presets:
+
+- Parse policy: `parseMode: 'strict' | 'permissive'`
+- Evaluation policy: `evaluateMode: 'exact' | 'numeric'` (`parseEvaluate`)
+- Simplification policy: `simplifyMode: 'default' | 'trigonometric'` (`parseSimplify`)
+
+Option precedence (explicit low-level options win):
+
+- `parse.strict` overrides `parseMode`
+- `evaluate.numericApproximation` overrides `evaluateMode`
+- `simplify.strategy` overrides `simplifyMode`
+
+## Extension Contracts
+
+Runtime contract checks are enforced for extension points:
+
+- `registerCompilationTarget(name, target)` validates target name format and required `LanguageTarget` methods (`getOperators()`, `getFunctions()`, `createTarget()`, `compile()`).
+- `new ComputeEngine({ libraries: [...] })` validates custom library shape (`name`, `requires`, `definitions`, `latexDictionary`).
+- `compile(expr, options)` validates extension-facing payload shape (`to`, `target`, `operators`, `functions`, `vars`, `imports`, `preamble`, `fallback`).
+
+## Snapshot Reports
+
+These files are useful implementation snapshots, but they are not a canonical
+API reference:
+
+- [`PLAYGROUND.md`](./PLAYGROUND.md)
+- [`SIMPLIFICATIONS.md`](./SIMPLIFICATIONS.md)
+- [`SIMPLIFY.md`](./SIMPLIFY.md)

docs/architecture/CURRENT-ARCHITECTURE.md

@@ -60,11 +60,11 @@ This document captures the implemented architecture after the recent modularizat
 | `engine-library-bootstrap.ts` | Resolves library entries, topological sort, loads definitions, collects LaTeX dictionaries |
 | `engine-common-symbols.ts` | Initializes well-known symbol bindings (True, False, Pi, E, Nothing) |
 
-### Parsing & Workflows
+### Parsing & Free Functions
 | File | Responsibility |
 |------|---------------|
 | `engine-parse-entrypoint.ts` | Engine-specific parse defaults, symbol type resolution, boxing of parse results |
-| `engine-workflow-entrypoints.ts` | High-level `parseSimplify/parseEvaluate/parseNumeric` combining parse + operation |
+| `free-functions.ts` | Top-level free functions (`parse`, `simplify`, `evaluate`, `N`, `assign`) backed by a lazy global engine |
 
 ### Validation & Errors
 | File | Responsibility |
@@ -101,25 +101,18 @@ This document captures the implemented architecture after the recent modularizat
 | `engine-compilation-targets.ts` | Registry for named compilation targets (JavaScript, GLSL, etc.) |
 | `engine-type-resolver.ts` | Type resolution callback for parser integration |
 
-## Public Workflow API Policy
-
-- `parseSimplify()`
-  - Parse presets: `parseMode = strict | permissive`
-  - Simplify presets: `simplifyMode = default | trigonometric`
-- `parseEvaluate()`
-  - Parse presets: `parseMode = strict | permissive`
-  - Evaluate presets: `evaluateMode = exact | numeric`
-- `parseNumeric()`
-  - Parse presets: `parseMode = strict | permissive`
-
-Precedence rule across workflow helpers:
-- Explicit low-level options always win over presets.
-  - `parse.strict` overrides `parseMode`
-  - `evaluate.numericApproximation` overrides `evaluateMode`
-  - `simplify.strategy` overrides `simplifyMode`
-- This is implemented via object spread: the preset sets a default, then `...options.parse` overwrites it.
-
-Note: `simplifyMode: 'trigonometric'` maps to the internal `strategy: 'fu'` (the Fu algorithm for trigonometric simplification, named after Fu, Zhong, and Zeng).
+## Free Functions & Lazy Global Engine
+
+Top-level free functions (`parse`, `simplify`, `evaluate`, `N`, `assign`) are exported from `index.ts` via `free-functions.ts`. They are backed by a lazily-instantiated global `ComputeEngine` accessible via `getDefaultEngine()`.
+
+- `parse(latex)` — parse a LaTeX string
+- `simplify(latex | expr)` — simplify a LaTeX string or BoxedExpression
+- `evaluate(latex | expr)` — evaluate a LaTeX string or BoxedExpression
+- `N(latex | expr)` — numeric approximation
+- `assign(id, value)` / `assign({...})` — assign values in the global engine
+- `getDefaultEngine()` — access the shared engine instance for configuration
+
+The global engine is created on first call to any free function, using a dynamic `require('./index')` inside `getDefaultEngine()` to avoid circular dependency (since `index.ts` re-exports `free-functions.ts`).
 
 ## Extension Contracts (Runtime Guards)
 

src/compute-engine.ts

@@ -32,6 +32,16 @@ export { BaseCompiler } from './compute-engine/compilation/base-compiler';
 export { expand } from './compute-engine/boxed-expression/expand';
 export { compile } from './compute-engine/compilation/compile-expression';
 
+// Free functions backed by a lazily-instantiated global engine
+export {
+  parse,
+  simplify,
+  evaluate,
+  N,
+  assign,
+  getDefaultEngine,
+} from './compute-engine/free-functions';
+
 export {
   isBoxedExpression,
   isBoxedNumber,