solve-engine 1.0.2 → 1.1.1

package/dist/{ScopeManager-B6GzdhVG.d.cts → ScopeManager-8vf02dwj.d.cts}

@@ -1,7 +1,7 @@
-import { V as Value } from './Value-CXJqDH9J.cjs';
-import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-B0xskcv5.cjs';
-import { E as EngineError } from './EngineError-LU7W7AgI.cjs';
-import { D as DiagnosticPipeline } from './pipeline-BEb3hujr.cjs';
+import { V as Value } from './Value-BUi1RA3S.cjs';
+import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-Bp9xeTmX.cjs';
+import { E as EngineError } from './EngineError-B61GS1jp.cjs';
+import { D as DiagnosticPipeline } from './pipeline-CtfJtPQc.cjs';
 import { VariableResolver } from './variables.cjs';
 
 /**
@@ -39,7 +39,7 @@ import { VariableResolver } from './variables.cjs';
  *   -100).
  * @param context - Registries belonging to the engine that created this VM.
  */
-declare function createVM(registry: OpRegistry, maxStackDepth?: number, maxInstructions?: number, maxFunctionRecursionDepth?: number, maxCollectionSize?: number, maxAllocatedElements?: number, maxFunctionCalls?: number, maxDateOffsetYears?: number, minDateOffsetYears?: number, context?: EngineContext): VM;
+declare function createVM(registry: OpRegistry, maxStackDepth?: number, maxInstructions?: number, maxFunctionRecursionDepth?: number, maxCollectionSize?: number, maxAllocatedElements?: number, maxFunctionCalls?: number, maxDateOffsetYears?: number, minDateOffsetYears?: number, context?: EngineContext, holidayPredicate?: (epochMs: number) => boolean): VM;
 /**
  * Compiled bytecode ready for VM execution.
  *
@@ -81,6 +81,44 @@ interface LineExecutionContext {
     getLineResult?: (lineNumber: number) => Value | undefined;
     /** Whether line `lineNumber` is a blank line or a `#` heading, the stopping condition for "total above"/"sum above"/"average above" aggregation. */
     isLineBoundary?: (lineNumber: number) => boolean;
+    /**
+     * The variables another line's expression reads, by 1-based line number, or
+     * `undefined` when the line has no evaluated expression (forward reference,
+     * out of range, or markdown). Goal seek (`packages/goalseek/`) uses it to
+     * refuse up front when the variable it was asked to vary is one the target
+     * line never reads, rather than searching a relationship that cannot move.
+     */
+    getLineReads?: (lineNumber: number) => string[] | undefined;
+    /**
+     * Re-evaluate another line's already-compiled expression with `variable`
+     * bound to `bound` for that one evaluation, without disturbing the
+     * document's own value for it. This is the primitive goal seek
+     * (`packages/goalseek/`) drives: binding a numeric candidate probes the
+     * relationship, binding a symbolic placeholder (with `symbolicTolerant`)
+     * reads it back in closed form. Returns an error Value when there is no
+     * document, the line is not a plain expression ready to run, or its
+     * re-evaluation itself faults. The binding is a call frame, so it shadows
+     * the document's value exactly the way a function parameter does and is
+     * gone the moment the probe returns.
+     */
+    evaluateLineWithBinding?: (lineNumber: number, variable: string, bound: Value, symbolicTolerant: boolean) => Value;
+    /**
+     * The hard ceiling on goal seek's bisection steps, from
+     * `config.vm.maxGoalSeekIterations`. Carried on the context so the search,
+     * which runs as a plugin function with no other view of engine config, is
+     * bounded by the host's configured limit rather than a hardcoded one.
+     */
+    goalSeekMaxIterations?: number;
+    /**
+     * The RAW markdown text of line `lineNumber` (1-based), or `undefined`
+     * when there is no real document or the line is out of range. Distinct
+     * from `getLineResult`, which returns a line's evaluated Value: a
+     * markdown table's rows are skipped by the evaluator and hold no result,
+     * so reading a column as data has to go back to the source text. Backs
+     * the tables package (`packages/tables/`), which walks upward from the
+     * current line to find the nearest table and read one of its columns.
+     */
+    getLineText?: (lineNumber: number) => string | undefined;
 }
 /**
  * Discriminated union returned by {@link executeBytecode}.
@@ -389,6 +427,17 @@ interface VM {
     defineUserFunction(name: string, params: string[], program: BytecodeProgram): void;
     getUserFunction(name: string): UserFunctionDef | undefined;
     hasUserFunction(name: string): boolean;
+    /**
+     * Every session-scoped variable currently defined, as `[name, value]` pairs,
+     * for snapshotting the VM's state (see `engine/EngineSnapshot.ts`). The
+     * returned array is a fresh copy, so mutating it does not touch the store,
+     * and it reads the flat document-variable table only, never a transient
+     * user-function call frame (those are call-scoped and gone by the time any
+     * snapshot is taken).
+     */
+    getVariableEntries(): [string, Value][];
+    /** Every user-defined function currently defined, as a fresh array copy, for snapshotting (see {@link getVariableEntries}). */
+    getUserFunctionDefs(): UserFunctionDef[];
     /** Register (or redefine) a bare equation (`a*x = rhs`), keyed by its free variable. See {@link EquationDef}. */
     defineEquation(variable: string, factorNames: string[], rhsProgram: BytecodeProgram): void;
     getEquation(variable: string): EquationDef | undefined;
@@ -431,6 +480,8 @@ interface VM {
     getMaxDateOffsetYears(): number;
     /** The same bound backwards, as a negative number of years. */
     getMinDateOffsetYears(): number;
+    /** Whether the host's public-holiday calendar marks `epochMs` a holiday, for working-day arithmetic. Always `false` when no calendar is configured (weekends-only). Set from `constants/Configuration.ts`'s `date.holidays`; see `vm/HolidayCalendar.ts`. */
+    isHoliday(epochMs: number): boolean;
     getInstructionCount(): number;
     incrementInstructions(n: number): void;
     /** Active AbortSignal for the current expression evaluation. Checked before cache writes. */

package/dist/{ScopeManager-udv4Twwq.d.ts → ScopeManager-CxA24W5n.d.ts}

@@ -1,7 +1,7 @@
-import { V as Value } from './Value-CXJqDH9J.js';
-import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-B0xskcv5.js';
-import { E as EngineError } from './EngineError-LU7W7AgI.js';
-import { D as DiagnosticPipeline } from './pipeline-B6k5lCB7.js';
+import { V as Value } from './Value-BUi1RA3S.js';
+import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-Bp9xeTmX.js';
+import { E as EngineError } from './EngineError-B61GS1jp.js';
+import { D as DiagnosticPipeline } from './pipeline-DCd5M6Gk.js';
 import { VariableResolver } from './variables.js';
 
 /**
@@ -39,7 +39,7 @@ import { VariableResolver } from './variables.js';
  *   -100).
  * @param context - Registries belonging to the engine that created this VM.
  */
-declare function createVM(registry: OpRegistry, maxStackDepth?: number, maxInstructions?: number, maxFunctionRecursionDepth?: number, maxCollectionSize?: number, maxAllocatedElements?: number, maxFunctionCalls?: number, maxDateOffsetYears?: number, minDateOffsetYears?: number, context?: EngineContext): VM;
+declare function createVM(registry: OpRegistry, maxStackDepth?: number, maxInstructions?: number, maxFunctionRecursionDepth?: number, maxCollectionSize?: number, maxAllocatedElements?: number, maxFunctionCalls?: number, maxDateOffsetYears?: number, minDateOffsetYears?: number, context?: EngineContext, holidayPredicate?: (epochMs: number) => boolean): VM;
 /**
  * Compiled bytecode ready for VM execution.
  *
@@ -81,6 +81,44 @@ interface LineExecutionContext {
     getLineResult?: (lineNumber: number) => Value | undefined;
     /** Whether line `lineNumber` is a blank line or a `#` heading, the stopping condition for "total above"/"sum above"/"average above" aggregation. */
     isLineBoundary?: (lineNumber: number) => boolean;
+    /**
+     * The variables another line's expression reads, by 1-based line number, or
+     * `undefined` when the line has no evaluated expression (forward reference,
+     * out of range, or markdown). Goal seek (`packages/goalseek/`) uses it to
+     * refuse up front when the variable it was asked to vary is one the target
+     * line never reads, rather than searching a relationship that cannot move.
+     */
+    getLineReads?: (lineNumber: number) => string[] | undefined;
+    /**
+     * Re-evaluate another line's already-compiled expression with `variable`
+     * bound to `bound` for that one evaluation, without disturbing the
+     * document's own value for it. This is the primitive goal seek
+     * (`packages/goalseek/`) drives: binding a numeric candidate probes the
+     * relationship, binding a symbolic placeholder (with `symbolicTolerant`)
+     * reads it back in closed form. Returns an error Value when there is no
+     * document, the line is not a plain expression ready to run, or its
+     * re-evaluation itself faults. The binding is a call frame, so it shadows
+     * the document's value exactly the way a function parameter does and is
+     * gone the moment the probe returns.
+     */
+    evaluateLineWithBinding?: (lineNumber: number, variable: string, bound: Value, symbolicTolerant: boolean) => Value;
+    /**
+     * The hard ceiling on goal seek's bisection steps, from
+     * `config.vm.maxGoalSeekIterations`. Carried on the context so the search,
+     * which runs as a plugin function with no other view of engine config, is
+     * bounded by the host's configured limit rather than a hardcoded one.
+     */
+    goalSeekMaxIterations?: number;
+    /**
+     * The RAW markdown text of line `lineNumber` (1-based), or `undefined`
+     * when there is no real document or the line is out of range. Distinct
+     * from `getLineResult`, which returns a line's evaluated Value: a
+     * markdown table's rows are skipped by the evaluator and hold no result,
+     * so reading a column as data has to go back to the source text. Backs
+     * the tables package (`packages/tables/`), which walks upward from the
+     * current line to find the nearest table and read one of its columns.
+     */
+    getLineText?: (lineNumber: number) => string | undefined;
 }
 /**
  * Discriminated union returned by {@link executeBytecode}.
@@ -389,6 +427,17 @@ interface VM {
     defineUserFunction(name: string, params: string[], program: BytecodeProgram): void;
     getUserFunction(name: string): UserFunctionDef | undefined;
     hasUserFunction(name: string): boolean;
+    /**
+     * Every session-scoped variable currently defined, as `[name, value]` pairs,
+     * for snapshotting the VM's state (see `engine/EngineSnapshot.ts`). The
+     * returned array is a fresh copy, so mutating it does not touch the store,
+     * and it reads the flat document-variable table only, never a transient
+     * user-function call frame (those are call-scoped and gone by the time any
+     * snapshot is taken).
+     */
+    getVariableEntries(): [string, Value][];
+    /** Every user-defined function currently defined, as a fresh array copy, for snapshotting (see {@link getVariableEntries}). */
+    getUserFunctionDefs(): UserFunctionDef[];
     /** Register (or redefine) a bare equation (`a*x = rhs`), keyed by its free variable. See {@link EquationDef}. */
     defineEquation(variable: string, factorNames: string[], rhsProgram: BytecodeProgram): void;
     getEquation(variable: string): EquationDef | undefined;
@@ -431,6 +480,8 @@ interface VM {
     getMaxDateOffsetYears(): number;
     /** The same bound backwards, as a negative number of years. */
     getMinDateOffsetYears(): number;
+    /** Whether the host's public-holiday calendar marks `epochMs` a holiday, for working-day arithmetic. Always `false` when no calendar is configured (weekends-only). Set from `constants/Configuration.ts`'s `date.holidays`; see `vm/HolidayCalendar.ts`. */
+    isHoliday(epochMs: number): boolean;
     getInstructionCount(): number;
     incrementInstructions(n: number): void;
     /** Active AbortSignal for the current expression evaluation. Checked before cache writes. */

package/dist/{Token-BzG5G4ja.d.cts → Token-B1hdkedD.d.cts}

@@ -48,6 +48,7 @@ declare const TokenTypes: {
     readonly MINUS: "MINUS";
     readonly STAR: "STAR";
     readonly SLASH: "SLASH";
+    readonly PLUS_MINUS: "PLUS_MINUS";
     readonly CARET: "CARET";
     readonly PERCENT: "PERCENT";
     readonly LSHIFT: "LSHIFT";
@@ -163,6 +164,8 @@ declare const TokenTypes: {
     readonly IS: "IS";
     readonly PCT_ON: "PCT_ON";
     readonly PCT_OFF: "PCT_OFF";
+    readonly PCT_UP: "PCT_UP";
+    readonly PCT_DOWN: "PCT_DOWN";
     readonly OF_WHAT: "OF_WHAT";
     readonly OFF_WHAT: "OFF_WHAT";
     readonly ON_WHAT: "ON_WHAT";
@@ -192,6 +195,8 @@ declare const TokenTypes: {
     readonly BACKTICK_OPEN: "BACKTICK_OPEN";
     readonly INLINE_SOLVE_START: "INLINE_SOLVE_START";
     readonly COMMENT: "COMMENT";
+    readonly HEX_COLOUR: "HEX_COLOUR";
+    readonly COLOUR_CALL: "COLOUR_CALL";
     readonly VEC2: "VEC2";
     readonly VEC3: "VEC3";
     readonly VEC4: "VEC4";
@@ -241,6 +246,9 @@ declare const TokenTypes: {
     readonly AT_RATE: "AT_RATE";
     readonly WEEK_IN: "WEEK_IN";
     readonly BETWEEN_UNIT: "BETWEEN_UNIT";
+    readonly WORKDAYS_AFTER: "WORKDAYS_AFTER";
+    readonly WORKDAYS_BEFORE: "WORKDAYS_BEFORE";
+    readonly WORKDAYS_BETWEEN: "WORKDAYS_BETWEEN";
     readonly IS_WEEKEND: "IS_WEEKEND";
     readonly IS_WORKDAY: "IS_WORKDAY";
     readonly VIDEO_TIMECODE: "VIDEO_TIMECODE";
@@ -254,6 +262,7 @@ declare const TokenTypes: {
     readonly TOTAL_ABOVE: "TOTAL_ABOVE";
     readonly SUM_ABOVE: "SUM_ABOVE";
     readonly AVERAGE_ABOVE: "AVERAGE_ABOVE";
+    readonly GOAL_SEEK: "GOAL_SEEK";
 };
 /**
  * A token's kind, as a string.

package/dist/{Token-BzG5G4ja.d.ts → Token-B1hdkedD.d.ts}

@@ -48,6 +48,7 @@ declare const TokenTypes: {
     readonly MINUS: "MINUS";
     readonly STAR: "STAR";
     readonly SLASH: "SLASH";
+    readonly PLUS_MINUS: "PLUS_MINUS";
     readonly CARET: "CARET";
     readonly PERCENT: "PERCENT";
     readonly LSHIFT: "LSHIFT";
@@ -163,6 +164,8 @@ declare const TokenTypes: {
     readonly IS: "IS";
     readonly PCT_ON: "PCT_ON";
     readonly PCT_OFF: "PCT_OFF";
+    readonly PCT_UP: "PCT_UP";
+    readonly PCT_DOWN: "PCT_DOWN";
     readonly OF_WHAT: "OF_WHAT";
     readonly OFF_WHAT: "OFF_WHAT";
     readonly ON_WHAT: "ON_WHAT";
@@ -192,6 +195,8 @@ declare const TokenTypes: {
     readonly BACKTICK_OPEN: "BACKTICK_OPEN";
     readonly INLINE_SOLVE_START: "INLINE_SOLVE_START";
     readonly COMMENT: "COMMENT";
+    readonly HEX_COLOUR: "HEX_COLOUR";
+    readonly COLOUR_CALL: "COLOUR_CALL";
     readonly VEC2: "VEC2";
     readonly VEC3: "VEC3";
     readonly VEC4: "VEC4";
@@ -241,6 +246,9 @@ declare const TokenTypes: {
     readonly AT_RATE: "AT_RATE";
     readonly WEEK_IN: "WEEK_IN";
     readonly BETWEEN_UNIT: "BETWEEN_UNIT";
+    readonly WORKDAYS_AFTER: "WORKDAYS_AFTER";
+    readonly WORKDAYS_BEFORE: "WORKDAYS_BEFORE";
+    readonly WORKDAYS_BETWEEN: "WORKDAYS_BETWEEN";
     readonly IS_WEEKEND: "IS_WEEKEND";
     readonly IS_WORKDAY: "IS_WORKDAY";
     readonly VIDEO_TIMECODE: "VIDEO_TIMECODE";
@@ -254,6 +262,7 @@ declare const TokenTypes: {
     readonly TOTAL_ABOVE: "TOTAL_ABOVE";
     readonly SUM_ABOVE: "SUM_ABOVE";
     readonly AVERAGE_ABOVE: "AVERAGE_ABOVE";
+    readonly GOAL_SEEK: "GOAL_SEEK";
 };
 /**
  * A token's kind, as a string.

package/dist/{TokenNormalizer-t_GotBxr.d.ts → TokenNormalizer-C6VzZgHa.d.ts}

@@ -1,4 +1,4 @@
-import { T as Token } from './Token-BzG5G4ja.js';
+import { T as Token } from './Token-B1hdkedD.js';
 
 /**
  * NormalizerRule, pluggable token normalization rule for the

package/dist/{TokenNormalizer-DGVa24Q-.d.cts → TokenNormalizer-DRc1Js1V.d.cts}

@@ -1,4 +1,4 @@
-import { T as Token } from './Token-BzG5G4ja.cjs';
+import { T as Token } from './Token-B1hdkedD.cjs';
 
 /**
  * NormalizerRule, pluggable token normalization rule for the

package/dist/{VMCheckpoints-DwLjivM7.d.cts → VMCheckpoints-ELYqITdF.d.cts}

@@ -1,6 +1,6 @@
-import { V as Value } from './Value-CXJqDH9J.cjs';
-import { V as VM } from './ScopeManager-B6GzdhVG.cjs';
-import { U as UserFunctionDef } from './BytecodeBuilder-B0xskcv5.cjs';
+import { V as Value } from './Value-BUi1RA3S.cjs';
+import { V as VM } from './ScopeManager-8vf02dwj.cjs';
+import { U as UserFunctionDef } from './BytecodeBuilder-Bp9xeTmX.cjs';
 
 /**
  * A point-in-time snapshot of VM variable state.

package/dist/{VMCheckpoints-BiaIlOOY.d.ts → VMCheckpoints-MK--EBH2.d.ts}

@@ -1,6 +1,6 @@
-import { V as Value } from './Value-CXJqDH9J.js';
-import { V as VM } from './ScopeManager-udv4Twwq.js';
-import { U as UserFunctionDef } from './BytecodeBuilder-B0xskcv5.js';
+import { V as Value } from './Value-BUi1RA3S.js';
+import { V as VM } from './ScopeManager-CxA24W5n.js';
+import { U as UserFunctionDef } from './BytecodeBuilder-Bp9xeTmX.js';
 
 /**
  * A point-in-time snapshot of VM variable state.

package/dist/{Value-CXJqDH9J.d.cts → Value-BUi1RA3S.d.cts}

@@ -136,6 +136,28 @@ type SymbolicNode = {
     args: readonly SymbolicNode[];
 };
 
+/**
+ * An exact base-ten number, held as an integer coefficient and a scale.
+ *
+ * The value is `coef * 10^(-scale)`, so `Decimal(30n, 2)` is exactly `0.30` and
+ * `Decimal(1005n, 3)` is exactly `1.005`. `scale` is a non-negative integer
+ * count of fractional digits, the sign lives on `coef`, and zero is
+ * `Decimal(0n, s)` for any `s`.
+ *
+ * This is the representation money is carried in so that two prices a user
+ * typed add and multiply without the binary-floating-point error a double
+ * introduces (`0.1 + 0.2` is `0.30000000000000004` as a double, `0.30` here).
+ * It is deliberately dependency-free: a bigint coefficient plus an integer
+ * scale needs nothing the runtime does not already have, which keeps the
+ * engine's single-runtime-dependency contract intact.
+ */
+interface DecimalData {
+    /** The integer coefficient, carrying the sign. */
+    readonly coef: bigint;
+    /** The number of fractional digits, a non-negative integer. */
+    readonly scale: number;
+}
+
 /**
  * A single matrix cell. `boolean` covers element-wise comparison results
  * (`[1,6;3,8] < [5,2;7,4]` produces a Matrix of booleans, not numbers). A
@@ -169,6 +191,33 @@ interface RangeData {
     readonly min: number;
     readonly max: number;
 }
+/**
+ * How a colour was authored, and therefore how it should display. It never
+ * changes the channels: a colour is always stored as canonical sRGB (`r`,`g`,`b`
+ * integers 0-255, `a` in 0-1), and `format` only decides whether `formatValue`
+ * renders it as `#rrggbb`, `rgb(...)`, `hsl(...)` or a named keyword.
+ */
+type ColourFormat = "hex" | "rgb" | "rgba" | "hsl" | "hsla" | "named";
+/**
+ * A colour value. Canonical channels are sRGB (`r`,`g`,`b` are integers 0-255,
+ * `a` is 0-1); HSL is never stored, it is derived on demand for display and for
+ * hue/saturation/lightness operations, then re-quantised back to RGBA. A
+ * `lighten` followed by an equal `darken` returns to within one rounding step of
+ * the original (integer channels re-quantise each way), and does not drift on
+ * repetition, rather than storing both HSL and RGB and letting them disagree.
+ * `format`
+ * records the authored/display form; `name` carries the CSS keyword only when
+ * `format === "named"` (e.g. `"rebeccapurple"`). Lives in a {@link Value}'s
+ * `value` slot exactly as {@link MatrixData}/{@link RangeData} do.
+ */
+interface ColourData {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly a: number;
+    readonly format: ColourFormat;
+    readonly name?: string;
+}
 /**
  * Discriminated union tag for {@link Value} objects.
  *
@@ -198,7 +247,9 @@ declare enum ValueType {
     /** Async result pending resolution. Value stores the queryKey string. */
     Pending = 12,
     /** Plugin-raised error propagated through the DAG. Value stores error code, unit stores message. */
-    Error = 13
+    Error = 13,
+    /** A colour (hex/rgb/hsl/named). Value is {@link ColourData}. */
+    Colour = 14
 }
 /**
  * Universal runtime value for the solve-js VM.
@@ -214,16 +265,81 @@ declare enum ValueType {
 declare class Value {
     private _cachedNumber;
     type: ValueType;
-    value: number | bigint | string | boolean | MatrixData | RangeData | SymbolicNode;
+    value: number | bigint | string | boolean | MatrixData | RangeData | ColourData | SymbolicNode;
     unit?: string;
     /** Set by async resolvers when a fetch timed out, the result is a fallback (typically 0). */
     timedOut?: boolean;
-    constructor(type: ValueType, value: number | bigint | string | boolean | MatrixData | RangeData | SymbolicNode, unit?: string);
+    /**
+     * The exact base-ten value this Value stands for, when it has one.
+     *
+     * A sidecar rather than a replacement for `value`: money and decimal-point
+     * literals set it to a {@link DecimalData} so that same-currency arithmetic
+     * and display can be exact ("$0.10 + $0.20" is "$0.30", not
+     * "$0.30000000000000004"), while `value` stays the nearest double so every
+     * existing consumer that reads `.value` or `toNumber()` is unchanged. The
+     * plain Number-times-Number fast paths deliberately ignore it, which is why
+     * a bare "0.1 + 0.2" still answers the double it always did: exactness is
+     * carried only where a unit-bearing operand asks for it. Cleared by
+     * {@link recycle} so a reused arena Value never inherits a stale exact.
+     */
+    exact?: DecimalData;
+    /**
+     * The exact rational value this Value stands for, when it has one.
+     *
+     * The second sidecar, the same shape as {@link exact} and for the same
+     * reason: a fraction has no exact base-ten form (`1/3` is not any decimal),
+     * so exact fraction arithmetic needs a numerator/denominator pair rather
+     * than a coefficient and a scale. Integer division seeds it ("1/3" carries
+     * the {@link Rational} 1/3), and `+`, `-`, `*`, `/` between rational-bearing
+     * numbers keep it reduced, so "1/49 * 49" is exactly 1 and "5/6 - 1/6 - 1/6
+     * - 1/6 - 1/6 - 1/6" is exactly 0 rather than the 1.6e-16 the doubles drift
+     * to. `value` still holds the nearest double, recomputed from the exact
+     * rational so accumulation error never creeps in, which is why the default
+     * display and every `.value`/`toNumber()` reader are unchanged. Only a
+     * fraction written with "/" carries it, so a decimal literal ("0.1") and a
+     * transcendental result ("sqrt(2)") stay the plain doubles they were.
+     * Cleared by {@link recycle} alongside {@link exact}.
+     */
+    rational?: Rational;
+    /**
+     * The one-sigma uncertainty (standard error) this value carries, when it
+     * has one.
+     *
+     * The third sidecar, the same shape as {@link exact} and {@link rational}
+     * and for the same reason: a measurement written `12.3 ± 0.5` is still the
+     * number 12.3 everywhere it is read as one, so the type stays
+     * {@link ValueType.Number} and `value` stays the center, while this non
+     * negative field carries the tolerance. The `±` (or ASCII `+/-`) operator
+     * seeds it, and `+`, `-`, `*`, `/` propagate it in quadrature for
+     * independent errors (see `vm/VMConversion.ts`'s `uncertainOp`). Everything
+     * else (a comparison, a transcendental function, a unit conversion) reads
+     * the center through `toNumber()` and drops the tolerance, which is why a
+     * value with no uncertainty behaves exactly as a plain number always did.
+     * Cleared by {@link recycle} alongside the other two sidecars.
+     */
+    uncertainty?: number;
+    /**
+     * The number of decimal places this value should DISPLAY at, when it has been
+     * given an explicit precision.
+     *
+     * A display sidecar, not a value one: `value` is unchanged, so every
+     * `.value`/`toNumber()` reader and all arithmetic behave exactly as before,
+     * and a value with no `decimalPlaces` formats the way it always did (the
+     * global two-place default with trailing zeros trimmed). It is set only by an
+     * explicit precision request, `<x> to N dp` and `round(x, N)`, so that
+     * `3.14159 to 4 dp` shows `3.1416` and `1.5 to 2 dp` shows `1.50` rather than
+     * the value being rounded but then displayed at the default two places. It is
+     * NOT propagated through arithmetic (a later `+ 1` re-decides precision),
+     * which is why nothing that did not ask for a precision is affected. Cleared
+     * by {@link recycle} alongside the other sidecars.
+     */
+    decimalPlaces?: number;
+    constructor(type: ValueType, value: number | bigint | string | boolean | MatrixData | RangeData | ColourData | SymbolicNode, unit?: string);
     /**
      * Phase 5.3: Reset all fields for arena reuse.
      * Called by ValueArena.acquire(), zero allocation, just field assignment.
      */
-    recycle(type: ValueType, value: number | bigint | string | boolean | MatrixData | RangeData | SymbolicNode, unit?: string): void;
+    recycle(type: ValueType, value: number | bigint | string | boolean | MatrixData | RangeData | ColourData | SymbolicNode, unit?: string): void;
     isNumber(): this is Value & {
         value: number;
     };
@@ -244,6 +360,9 @@ declare class Value {
     isRange(): this is Value & {
         value: RangeData;
     };
+    isColour(): this is Value & {
+        value: ColourData;
+    };
     isSymbolic(): this is Value & {
         value: SymbolicNode;
     };
@@ -295,4 +414,4 @@ declare function colVectorValue(data: readonly number[]): Value;
 /** Create a Range value, a first-class integer range `min:max`, both bounds inclusive. */
 declare function rangeValue(min: number, max: number): Value;
 
-export { type MatrixData as M, type RangeData as R, type SymbolicNode as S, Value as V, type MatrixEntry as a, ValueType as b, bigIntValue as c, colVectorValue as d, rowVectorValue as e, hexValue as h, matrixValue as m, numberValue as n, rangeValue as r, stringValue as s, uomValue as u };
+export { type ColourData as C, type MatrixData as M, type RangeData as R, type SymbolicNode as S, Value as V, type MatrixEntry as a, ValueType as b, bigIntValue as c, colVectorValue as d, rowVectorValue as e, type ColourFormat as f, hexValue as h, matrixValue as m, numberValue as n, rangeValue as r, stringValue as s, uomValue as u };

package/dist/{Value-CXJqDH9J.d.ts → Value-BUi1RA3S.d.ts}

@@ -136,6 +136,28 @@ type SymbolicNode = {
     args: readonly SymbolicNode[];
 };
 
+/**
+ * An exact base-ten number, held as an integer coefficient and a scale.
+ *
+ * The value is `coef * 10^(-scale)`, so `Decimal(30n, 2)` is exactly `0.30` and
+ * `Decimal(1005n, 3)` is exactly `1.005`. `scale` is a non-negative integer
+ * count of fractional digits, the sign lives on `coef`, and zero is
+ * `Decimal(0n, s)` for any `s`.
+ *
+ * This is the representation money is carried in so that two prices a user
+ * typed add and multiply without the binary-floating-point error a double
+ * introduces (`0.1 + 0.2` is `0.30000000000000004` as a double, `0.30` here).
+ * It is deliberately dependency-free: a bigint coefficient plus an integer
+ * scale needs nothing the runtime does not already have, which keeps the
+ * engine's single-runtime-dependency contract intact.
+ */
+interface DecimalData {
+    /** The integer coefficient, carrying the sign. */
+    readonly coef: bigint;
+    /** The number of fractional digits, a non-negative integer. */
+    readonly scale: number;
+}
+
 /**
  * A single matrix cell. `boolean` covers element-wise comparison results
  * (`[1,6;3,8] < [5,2;7,4]` produces a Matrix of booleans, not numbers). A
@@ -169,6 +191,33 @@ interface RangeData {
     readonly min: number;
     readonly max: number;
 }
+/**
+ * How a colour was authored, and therefore how it should display. It never
+ * changes the channels: a colour is always stored as canonical sRGB (`r`,`g`,`b`
+ * integers 0-255, `a` in 0-1), and `format` only decides whether `formatValue`
+ * renders it as `#rrggbb`, `rgb(...)`, `hsl(...)` or a named keyword.
+ */
+type ColourFormat = "hex" | "rgb" | "rgba" | "hsl" | "hsla" | "named";
+/**
+ * A colour value. Canonical channels are sRGB (`r`,`g`,`b` are integers 0-255,
+ * `a` is 0-1); HSL is never stored, it is derived on demand for display and for
+ * hue/saturation/lightness operations, then re-quantised back to RGBA. A
+ * `lighten` followed by an equal `darken` returns to within one rounding step of
+ * the original (integer channels re-quantise each way), and does not drift on
+ * repetition, rather than storing both HSL and RGB and letting them disagree.
+ * `format`
+ * records the authored/display form; `name` carries the CSS keyword only when
+ * `format === "named"` (e.g. `"rebeccapurple"`). Lives in a {@link Value}'s
+ * `value` slot exactly as {@link MatrixData}/{@link RangeData} do.
+ */
+interface ColourData {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly a: number;
+    readonly format: ColourFormat;
+    readonly name?: string;
+}
 /**
  * Discriminated union tag for {@link Value} objects.
  *
@@ -198,7 +247,9 @@ declare enum ValueType {
     /** Async result pending resolution. Value stores the queryKey string. */
     Pending = 12,
     /** Plugin-raised error propagated through the DAG. Value stores error code, unit stores message. */
-    Error = 13
+    Error = 13,
+    /** A colour (hex/rgb/hsl/named). Value is {@link ColourData}. */
+    Colour = 14
 }
 /**
  * Universal runtime value for the solve-js VM.
@@ -214,16 +265,81 @@ declare enum ValueType {
 declare class Value {
     private _cachedNumber;
     type: ValueType;
-    value: number | bigint | string | boolean | MatrixData | RangeData | SymbolicNode;
+    value: number | bigint | string | boolean | MatrixData | RangeData | ColourData | SymbolicNode;
     unit?: string;
     /** Set by async resolvers when a fetch timed out, the result is a fallback (typically 0). */
     timedOut?: boolean;
-    constructor(type: ValueType, value: number | bigint | string | boolean | MatrixData | RangeData | SymbolicNode, unit?: string);
+    /**
+     * The exact base-ten value this Value stands for, when it has one.
+     *
+     * A sidecar rather than a replacement for `value`: money and decimal-point
+     * literals set it to a {@link DecimalData} so that same-currency arithmetic
+     * and display can be exact ("$0.10 + $0.20" is "$0.30", not
+     * "$0.30000000000000004"), while `value` stays the nearest double so every
+     * existing consumer that reads `.value` or `toNumber()` is unchanged. The
+     * plain Number-times-Number fast paths deliberately ignore it, which is why
+     * a bare "0.1 + 0.2" still answers the double it always did: exactness is
+     * carried only where a unit-bearing operand asks for it. Cleared by
+     * {@link recycle} so a reused arena Value never inherits a stale exact.
+     */
+    exact?: DecimalData;
+    /**
+     * The exact rational value this Value stands for, when it has one.
+     *
+     * The second sidecar, the same shape as {@link exact} and for the same
+     * reason: a fraction has no exact base-ten form (`1/3` is not any decimal),
+     * so exact fraction arithmetic needs a numerator/denominator pair rather
+     * than a coefficient and a scale. Integer division seeds it ("1/3" carries
+     * the {@link Rational} 1/3), and `+`, `-`, `*`, `/` between rational-bearing
+     * numbers keep it reduced, so "1/49 * 49" is exactly 1 and "5/6 - 1/6 - 1/6
+     * - 1/6 - 1/6 - 1/6" is exactly 0 rather than the 1.6e-16 the doubles drift
+     * to. `value` still holds the nearest double, recomputed from the exact
+     * rational so accumulation error never creeps in, which is why the default
+     * display and every `.value`/`toNumber()` reader are unchanged. Only a
+     * fraction written with "/" carries it, so a decimal literal ("0.1") and a
+     * transcendental result ("sqrt(2)") stay the plain doubles they were.
+     * Cleared by {@link recycle} alongside {@link exact}.
+     */
+    rational?: Rational;
+    /**
+     * The one-sigma uncertainty (standard error) this value carries, when it
+     * has one.
+     *
+     * The third sidecar, the same shape as {@link exact} and {@link rational}
+     * and for the same reason: a measurement written `12.3 ± 0.5` is still the
+     * number 12.3 everywhere it is read as one, so the type stays
+     * {@link ValueType.Number} and `value` stays the center, while this non
+     * negative field carries the tolerance. The `±` (or ASCII `+/-`) operator
+     * seeds it, and `+`, `-`, `*`, `/` propagate it in quadrature for
+     * independent errors (see `vm/VMConversion.ts`'s `uncertainOp`). Everything
+     * else (a comparison, a transcendental function, a unit conversion) reads
+     * the center through `toNumber()` and drops the tolerance, which is why a
+     * value with no uncertainty behaves exactly as a plain number always did.
+     * Cleared by {@link recycle} alongside the other two sidecars.
+     */
+    uncertainty?: number;
+    /**
+     * The number of decimal places this value should DISPLAY at, when it has been
+     * given an explicit precision.
+     *
+     * A display sidecar, not a value one: `value` is unchanged, so every
+     * `.value`/`toNumber()` reader and all arithmetic behave exactly as before,
+     * and a value with no `decimalPlaces` formats the way it always did (the
+     * global two-place default with trailing zeros trimmed). It is set only by an
+     * explicit precision request, `<x> to N dp` and `round(x, N)`, so that
+     * `3.14159 to 4 dp` shows `3.1416` and `1.5 to 2 dp` shows `1.50` rather than
+     * the value being rounded but then displayed at the default two places. It is
+     * NOT propagated through arithmetic (a later `+ 1` re-decides precision),
+     * which is why nothing that did not ask for a precision is affected. Cleared
+     * by {@link recycle} alongside the other sidecars.
+     */
+    decimalPlaces?: number;
+    constructor(type: ValueType, value: number | bigint | string | boolean | MatrixData | RangeData | ColourData | SymbolicNode, unit?: string);
     /**
      * Phase 5.3: Reset all fields for arena reuse.
      * Called by ValueArena.acquire(), zero allocation, just field assignment.
      */
-    recycle(type: ValueType, value: number | bigint | string | boolean | MatrixData | RangeData | SymbolicNode, unit?: string): void;
+    recycle(type: ValueType, value: number | bigint | string | boolean | MatrixData | RangeData | ColourData | SymbolicNode, unit?: string): void;
     isNumber(): this is Value & {
         value: number;
     };
@@ -244,6 +360,9 @@ declare class Value {
     isRange(): this is Value & {
         value: RangeData;
     };
+    isColour(): this is Value & {
+        value: ColourData;
+    };
     isSymbolic(): this is Value & {
         value: SymbolicNode;
     };
@@ -295,4 +414,4 @@ declare function colVectorValue(data: readonly number[]): Value;
 /** Create a Range value, a first-class integer range `min:max`, both bounds inclusive. */
 declare function rangeValue(min: number, max: number): Value;
 
-export { type MatrixData as M, type RangeData as R, type SymbolicNode as S, Value as V, type MatrixEntry as a, ValueType as b, bigIntValue as c, colVectorValue as d, rowVectorValue as e, hexValue as h, matrixValue as m, numberValue as n, rangeValue as r, stringValue as s, uomValue as u };
+export { type ColourData as C, type MatrixData as M, type RangeData as R, type SymbolicNode as S, Value as V, type MatrixEntry as a, ValueType as b, bigIntValue as c, colVectorValue as d, rowVectorValue as e, type ColourFormat as f, hexValue as h, matrixValue as m, numberValue as n, rangeValue as r, stringValue as s, uomValue as u };