@faicad/faijs 0.19.0 → 0.22.2

package/dist/units.d.ts

@@ -0,0 +1,248 @@
+/**
+ * faijs unit system — the single source of truth for dimensions and units.
+ *
+ * Every dimensioned value in faijs is stored in the **base unit** of its
+ * dimension, and units are pure scale factors relative to that base. This
+ * module is a zero-dependency leaf: it must not import `lang/`, any op
+ * registry, `occt-kernel/*` or `brepkit-kernel/*`, because it feeds the
+ * serialization pipeline (codegen), platform-neutral imports, and static
+ * dimension checks without dragging in a WASM chain.
+ *
+ * Base units (user-裁定, 2026-09-28):
+ *   length: mm | angle: degree | mass: gram | temperature: kelvin
+ *   time: second | current: ampere
+ *
+ * `ValueWithUnits.value` is ALWAYS the base-unit numeric value. There is no
+ * "this value remembers it is inches" — conversion happens only at construction
+ * (`inch.mul(2)`) and extraction (`.as(mm)`), which mirrors Onshape's design
+ * but with faijs's own base table (NOT Onshape's meter/radian — do not copy
+ * those numeric values).
+ */
+/** Base dimensions of the system. Higher powers are built by exponents. */
+export type BaseDimension = 'length' | 'angle' | 'mass' | 'temperature' | 'time' | 'current';
+/** A dim name is any base dimension. */
+export type DimName = BaseDimension;
+/**
+ * A unit name. `micron/mm/cm/m/inch/foot/meter` are the six legal values of
+ * the 3MF `<model unit>` enum and must all be present in `UNIT_SCALE`.
+ */
+export type UnitName = 'mm' | 'cm' | 'm' | 'micron' | 'inch' | 'foot' | 'yard' | 'degree' | 'radian' | 'gram' | 'kilogram' | 'second';
+/**
+ * A dimension = a sparse map of base dimension → exponent (absent ⇒ 0).
+ * Implemented as a frozen plain object.
+ */
+export type UnitSpec = Readonly<Partial<Record<BaseDimension, number>>>;
+/**
+ * True when two specs have identical exponents for every base dimension.
+ * @param a - first spec.
+ * @param b - second spec.
+ * @returns `true` if every base-dimension exponent matches.
+ */
+export declare function unitEquals(a: UnitSpec, b: UnitSpec): boolean;
+/** Dimension spec for length (length^1). */
+export declare const LENGTH: UnitSpec;
+/** Dimension spec for area (length^2). */
+export declare const AREA: UnitSpec;
+/** Dimension spec for volume (length^3). */
+export declare const VOLUME: UnitSpec;
+/** Dimension spec for angle (angle^1). */
+export declare const ANGLE: UnitSpec;
+/** Dimension spec for mass (mass^1). */
+export declare const MASS: UnitSpec;
+/** Dimension spec for temperature (temperature^1). */
+export declare const TEMPERATURE: UnitSpec;
+/** Dimension spec for time (time^1). */
+export declare const TIME: UnitSpec;
+/** Dimension spec for electric current (current^1). */
+export declare const CURRENT: UnitSpec;
+/**
+ * The dimension spec of a named base dimension.
+ * @param dim - a base dimension name.
+ * @returns the corresponding `UnitSpec`.
+ */
+export declare function specOfDim(dim: DimName): UnitSpec;
+/**
+ * A value carrying an immutable dimension. All arithmetic is method-style —
+ * there is no operator overloading in TS. `value` is always expressed in the
+ * base unit of its dimension.
+ */
+export declare class ValueWithUnits {
+    /** The numeric magnitude, always expressed in the base unit of the dimension. */
+    readonly value: number;
+    /** The dimension spec (which base dimensions are present and with what exponent). */
+    readonly spec: UnitSpec;
+    constructor(value: number, spec: UnitSpec);
+    /**
+     * Add another value; both must share the same dimension.
+     * @param rhs - the value to add (must have the same dimension).
+     * @returns a new `ValueWithUnits` whose value is `this.value + rhs.value`.
+     */
+    add(rhs: ValueWithUnits): ValueWithUnits;
+    /**
+     * Subtract another value; both must share the same dimension.
+     * @param rhs - the value to subtract (must have the same dimension).
+     * @returns a new `ValueWithUnits` whose value is `this.value - rhs.value`.
+     */
+    sub(rhs: ValueWithUnits): ValueWithUnits;
+    /**
+     * Negate.
+     * @returns a new `ValueWithUnits` with the negated magnitude.
+     */
+    neg(): ValueWithUnits;
+    /**
+     * Scale by a dimensionless number.
+     * @param n - a dimensionless scalar.
+     * @returns a new `ValueWithUnits` with the scaled magnitude.
+     */
+    mul(n: number): ValueWithUnits;
+    /**
+     * Divide by a dimensionless number.
+     * @param n - a dimensionless scalar.
+     * @returns a new `ValueWithUnits` with the divided magnitude.
+     */
+    div(n: number): ValueWithUnits;
+    /**
+     * The ratio to another value of the same dimension (dimensionless result).
+     * @param rhs - the divisor (must have the same dimension).
+     * @returns the dimensionless ratio `this.value / rhs.value`.
+     */
+    divBy(rhs: ValueWithUnits): number;
+    /**
+     * Raise to an integer power; each exponent times n must stay an integer.
+     * @param n - the integer power.
+     * @returns a new `ValueWithUnits` with exponents multiplied by `n`.
+     */
+    pow(n: number): ValueWithUnits;
+    /**
+     * Extract the numeric magnitude expressed in another unit (dimension must match).
+     * @param unit - a `ValueWithUnits` representing 1 of the target unit.
+     * @returns the magnitude in that unit.
+     */
+    as(unit: ValueWithUnits): number;
+    /**
+     * True when the magnitude is ~0 (within an optional same-dimension epsilon).
+     * @param eps - optional same-dimension epsilon; defaults to 1e-9 base units.
+     * @returns `true` when `|value| <= eps`.
+     */
+    eqZero(eps?: ValueWithUnits): boolean;
+}
+/**
+ * Unit name → base-unit scale factor. `length`: 1 mm; `angle`: 1 degree;
+ * `mass`: 1 gram; `time`: 1 second.
+ */
+export declare const UNIT_SCALE: Readonly<Record<UnitName, number>>;
+/** Unit name → the dimension it measures. */
+export declare const UNIT_DIM: Readonly<Record<UnitName, DimName>>;
+/** Derived: unit name → UnitSpec. */
+export declare const UNIT_DIMS: Readonly<Record<UnitName, UnitSpec>>;
+/**
+ * Script-side unit constant names → their numeric values (base-unit scale).
+ * These are registered as global read-only constants in the script runtime.
+ * All names are UPPERCASE to avoid collisions with user variable names
+ * (e.g. `cm` as center-of-mass would clash with `cm` as centimeter).
+ * `10 * INCH` in a script evaluates to `10 * 25.4 === 254` (plain JS multiply).
+ */
+export declare const SCRIPT_UNIT_CONSTANTS: Readonly<Record<string, number>>;
+/**
+ * Mapping from script-side unit constant names (UPPERCASE) to the internal
+ * `UnitName` (lowercase, used by UNIT_SCALE/UNIT_DIM for format-level units).
+ * Used by the dimension checker to resolve a script constant to its dimension.
+ */
+export declare const SCRIPT_UNIT_TO_NAME: Readonly<Record<string, UnitName>>;
+/** The set of script-side unit constant names (for fast membership tests). */
+export declare const SCRIPT_UNIT_NAMES: ReadonlySet<string>;
+/** 1 mm — the base length unit. */
+export declare const mm: ValueWithUnits;
+/** 1 cm = 10 mm. */
+export declare const centimeter: ValueWithUnits;
+/** 1 m = 1000 mm. */
+export declare const meter: ValueWithUnits;
+/** 1 micron = 0.001 mm (one of the 3MF unit enum values). */
+export declare const micron: ValueWithUnits;
+/** 1 inch = 25.4 mm. */
+export declare const inch: ValueWithUnits;
+/** 1 foot = 304.8 mm. */
+export declare const foot: ValueWithUnits;
+/** 1 yard = 914.4 mm. */
+export declare const yard: ValueWithUnits;
+/** The base angle unit — 1 degree. */
+export declare const degree: ValueWithUnits;
+/** 1 radian = 180/π degrees (base is degree). */
+export declare const radian: ValueWithUnits;
+/** 1 gram (base mass unit). */
+export declare const gram: ValueWithUnits;
+/** 1 kilogram = 1000 gram. */
+export declare const kilogram: ValueWithUnits;
+/** 1 second (base time unit). */
+export declare const second: ValueWithUnits;
+/** 1 (mm). */
+export declare const MM = 1;
+/** 10 (mm). */
+export declare const CM = 10;
+/** 1000 (mm). */
+export declare const M = 1000;
+/** 0.001 (mm). */
+export declare const MICRON = 0.001;
+/** 25.4 (mm). */
+export declare const INCH = 25.4;
+/** 304.8 (mm). */
+export declare const FOOT = 304.8;
+/** 914.4 (mm). */
+export declare const YARD = 914.4;
+/** 1 (degree). */
+export declare const DEGREE = 1;
+/** 180/π (degree). */
+export declare const RADIAN: number;
+/**
+ * The system display unit context, owned by the host (never a module-level
+ * global). Defaults to the base units.
+ */
+export interface UnitContext {
+    length: UnitName;
+    angle: UnitName;
+}
+/** Base display units (mm / degree). */
+export declare const BASE_UNITS: UnitContext;
+/**
+ * The display unit for a dimension within a context. Only `length` and
+ * `angle` are host-settable; all other dimensions fall back to their base unit.
+ * @param dim - the dimension to look up.
+ * @param ctx - the system unit context; defaults to base units.
+ * @returns the unit name.
+ */
+export declare function unitFor(dim: DimName, ctx?: UnitContext): UnitName;
+/**
+ * Scale factor of a unit name relative to the base unit.
+ * @param name - the unit name.
+ * @returns the scale factor (e.g. `inch` → `25.4`).
+ */
+export declare function unitScale(name: UnitName): number;
+/**
+ * Convert a value given in a display unit to the base-unit value.
+ * @param n - the value in `unitName`.
+ * @param unitName - the source unit.
+ * @param dimensionName - the dimension (for validation).
+ * @returns the base-unit (mm/degree/...) value.
+ */
+export declare function toBase(n: number, unitName: UnitName, dimensionName: DimName): number;
+/**
+ * Convert a base-unit value into a display unit.
+ * @param base - the base-unit (mm/degree/...) value.
+ * @param unitName - the target unit.
+ * @param dimensionName - the dimension (for validation).
+ * @returns the value expressed in `unitName`.
+ */
+export declare function fromBase(base: number, unitName: UnitName, dimensionName: DimName): number;
+/**
+ * True when the value has dimension length.
+ * @param v - the value to check.
+ * @returns `true` if `v.spec` equals `LENGTH`.
+ */
+export declare function isLength(v: ValueWithUnits): boolean;
+/**
+ * True when the value has dimension angle.
+ * @param v - the value to check.
+ * @returns `true` if `v.spec` equals `ANGLE`.
+ */
+export declare function isAngle(v: ValueWithUnits): boolean;
+//# sourceMappingURL=units.d.ts.map

package/dist/units.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../src/units.ts"],"names":[],"mappings":"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"}

package/dist/units.js

@@ -0,0 +1,397 @@
+/**
+ * faijs unit system — the single source of truth for dimensions and units.
+ *
+ * Every dimensioned value in faijs is stored in the **base unit** of its
+ * dimension, and units are pure scale factors relative to that base. This
+ * module is a zero-dependency leaf: it must not import `lang/`, any op
+ * registry, `occt-kernel/*` or `brepkit-kernel/*`, because it feeds the
+ * serialization pipeline (codegen), platform-neutral imports, and static
+ * dimension checks without dragging in a WASM chain.
+ *
+ * Base units (user-裁定, 2026-09-28):
+ *   length: mm | angle: degree | mass: gram | temperature: kelvin
+ *   time: second | current: ampere
+ *
+ * `ValueWithUnits.value` is ALWAYS the base-unit numeric value. There is no
+ * "this value remembers it is inches" — conversion happens only at construction
+ * (`inch.mul(2)`) and extraction (`.as(mm)`), which mirrors Onshape's design
+ * but with faijs's own base table (NOT Onshape's meter/radian — do not copy
+ * those numeric values).
+ */
+/**
+ * True when two specs have identical exponents for every base dimension.
+ * @param a - first spec.
+ * @param b - second spec.
+ * @returns `true` if every base-dimension exponent matches.
+ */
+export function unitEquals(a, b) {
+    for (const dim of ALL_DIMS) {
+        const ea = a[dim] ?? 0;
+        const eb = b[dim] ?? 0;
+        if (ea !== eb)
+            return false;
+    }
+    return true;
+}
+/** All base dimensions, in a stable order. */
+const ALL_DIMS = [
+    'length', 'angle', 'mass', 'temperature', 'time', 'current',
+];
+/** Dimension spec for length (length^1). */
+export const LENGTH = Object.freeze({ length: 1 });
+/** Dimension spec for area (length^2). */
+export const AREA = Object.freeze({ length: 2 });
+/** Dimension spec for volume (length^3). */
+export const VOLUME = Object.freeze({ length: 3 });
+/** Dimension spec for angle (angle^1). */
+export const ANGLE = Object.freeze({ angle: 1 });
+/** Dimension spec for mass (mass^1). */
+export const MASS = Object.freeze({ mass: 1 });
+/** Dimension spec for temperature (temperature^1). */
+export const TEMPERATURE = Object.freeze({ temperature: 1 });
+/** Dimension spec for time (time^1). */
+export const TIME = Object.freeze({ time: 1 });
+/** Dimension spec for electric current (current^1). */
+export const CURRENT = Object.freeze({ current: 1 });
+/**
+ * The dimension spec of a named base dimension.
+ * @param dim - a base dimension name.
+ * @returns the corresponding `UnitSpec`.
+ */
+export function specOfDim(dim) {
+    switch (dim) {
+        case 'length': return LENGTH;
+        case 'angle': return ANGLE;
+        case 'mass': return MASS;
+        case 'temperature': return TEMPERATURE;
+        case 'time': return TIME;
+        case 'current': return CURRENT;
+    }
+}
+/**
+ * A value carrying an immutable dimension. All arithmetic is method-style —
+ * there is no operator overloading in TS. `value` is always expressed in the
+ * base unit of its dimension.
+ */
+export class ValueWithUnits {
+    /** The numeric magnitude, always expressed in the base unit of the dimension. */
+    value;
+    /** The dimension spec (which base dimensions are present and with what exponent). */
+    spec;
+    constructor(value, spec) {
+        this.value = value;
+        this.spec = issueFrozen(spec);
+    }
+    /**
+     * Add another value; both must share the same dimension.
+     * @param rhs - the value to add (must have the same dimension).
+     * @returns a new `ValueWithUnits` whose value is `this.value + rhs.value`.
+     */
+    add(rhs) {
+        requireSameDim(this, rhs, 'add');
+        return new ValueWithUnits(this.value + rhs.value, this.spec);
+    }
+    /**
+     * Subtract another value; both must share the same dimension.
+     * @param rhs - the value to subtract (must have the same dimension).
+     * @returns a new `ValueWithUnits` whose value is `this.value - rhs.value`.
+     */
+    sub(rhs) {
+        requireSameDim(this, rhs, 'sub');
+        return new ValueWithUnits(this.value - rhs.value, this.spec);
+    }
+    /**
+     * Negate.
+     * @returns a new `ValueWithUnits` with the negated magnitude.
+     */
+    neg() {
+        return new ValueWithUnits(-this.value, this.spec);
+    }
+    /**
+     * Scale by a dimensionless number.
+     * @param n - a dimensionless scalar.
+     * @returns a new `ValueWithUnits` with the scaled magnitude.
+     */
+    mul(n) {
+        return new ValueWithUnits(this.value * n, this.spec);
+    }
+    /**
+     * Divide by a dimensionless number.
+     * @param n - a dimensionless scalar.
+     * @returns a new `ValueWithUnits` with the divided magnitude.
+     */
+    div(n) {
+        return new ValueWithUnits(this.value / n, this.spec);
+    }
+    /**
+     * The ratio to another value of the same dimension (dimensionless result).
+     * @param rhs - the divisor (must have the same dimension).
+     * @returns the dimensionless ratio `this.value / rhs.value`.
+     */
+    divBy(rhs) {
+        requireSameDim(this, rhs, 'divBy');
+        return this.value / rhs.value;
+    }
+    /**
+     * Raise to an integer power; each exponent times n must stay an integer.
+     * @param n - the integer power.
+     * @returns a new `ValueWithUnits` with exponents multiplied by `n`.
+     */
+    pow(n) {
+        if (!Number.isInteger(n)) {
+            throw dimensionalError('pow exponent must be an integer', this);
+        }
+        const out = { length: 0, angle: 0, mass: 0, temperature: 0, time: 0, current: 0 };
+        for (const dim of ALL_DIMS) {
+            const e = this.spec[dim] ?? 0;
+            const ne = e * n;
+            if (!Number.isInteger(ne)) {
+                throw new Error(`[units] pow(${n}) would produce a non-integer exponent ${ne} for dimension ${dim}`);
+            }
+            out[dim] = ne;
+        }
+        return new ValueWithUnits(this.value ** n, normalizeSpec(out));
+    }
+    /**
+     * Extract the numeric magnitude expressed in another unit (dimension must match).
+     * @param unit - a `ValueWithUnits` representing 1 of the target unit.
+     * @returns the magnitude in that unit.
+     */
+    as(unit) {
+        requireSameDim(this, unit, 'as');
+        return this.value / unit.value;
+    }
+    /**
+     * True when the magnitude is ~0 (within an optional same-dimension epsilon).
+     * @param eps - optional same-dimension epsilon; defaults to 1e-9 base units.
+     * @returns `true` when `|value| <= eps`.
+     */
+    eqZero(eps) {
+        if (eps === undefined) {
+            // Default epsilon is one atomic stride of the base unit.
+            return Math.abs(this.value) <= 1e-9;
+        }
+        requireSameDim(this, eps, 'eqZero');
+        return Math.abs(this.value) <= Math.abs(eps.value);
+    }
+}
+/** Builder for an error that carries both dimensions of a mismatch. */
+function dimensionalError(action, a, b) {
+    const extras = b === undefined ? '' : ` vs {${describeSpec(b.spec)}}`;
+    return new Error(`[units] dimension mismatch in \`${action}\`: {${describeSpec(a.spec)}}${extras}`);
+}
+function requireSameDim(a, b, action) {
+    if (!unitEquals(a.spec, b.spec))
+        throw dimensionalError(action, a, b);
+}
+function describeSpec(spec) {
+    const parts = ALL_DIMS.filter((d) => (spec[d] ?? 0) !== 0)
+        .map((d) => `${d}^${spec[d]}`);
+    return parts.length ? parts.join('·') : 'dimensionless';
+}
+/** Freeze a spec; never expose a mutable spec to callers. */
+function issueFrozen(spec) {
+    return Object.freeze({ ...spec });
+}
+function normalizeSpec(spec) {
+    return Object.freeze({ ...spec });
+}
+// ── Single-source-of-truth tables ──────────────────────────────────────────
+// `UNIT_SCALE` + `UNIT_DIM` are the only data. `UNIT_DIMS`, the typed
+// constants, the pure-number constants and everything else derive from them.
+/**
+ * Unit name → base-unit scale factor. `length`: 1 mm; `angle`: 1 degree;
+ * `mass`: 1 gram; `time`: 1 second.
+ */
+export const UNIT_SCALE = Object.freeze({
+    // length (base = mm)
+    mm: 1,
+    cm: 10,
+    m: 1000,
+    micron: 0.001,
+    inch: 25.4,
+    foot: 304.8,
+    yard: 914.4,
+    // angle (base = degree)
+    degree: 1,
+    radian: 180 / Math.PI,
+    // mass (base = gram)
+    gram: 1,
+    kilogram: 1000,
+    // time (base = second)
+    second: 1,
+});
+/** Unit name → the dimension it measures. */
+export const UNIT_DIM = Object.freeze({
+    mm: 'length', cm: 'length', m: 'length', micron: 'length',
+    inch: 'length', foot: 'length', yard: 'length',
+    degree: 'angle', radian: 'angle',
+    gram: 'mass', kilogram: 'mass',
+    second: 'time',
+});
+/** Derived: unit name → UnitSpec. */
+export const UNIT_DIMS = Object.freeze(Object.keys(UNIT_SCALE).reduce((acc, name) => {
+    acc[name] = specOfDim(UNIT_DIM[name]);
+    return acc;
+}, {}));
+// ── Script-side unit constants (D7) ──────────────────────────────────────────
+// These are the bare-number constants available in .fai.js scripts.
+// `cm` and `meter` are script-friendly aliases for UNIT_SCALE keys `cm` and `m`.
+// The value is the base-unit scale factor (= UNIT_SCALE[name] for most, except
+// `meter` which maps to `m`).
+/**
+ * Script-side unit constant names → their numeric values (base-unit scale).
+ * These are registered as global read-only constants in the script runtime.
+ * All names are UPPERCASE to avoid collisions with user variable names
+ * (e.g. `cm` as center-of-mass would clash with `cm` as centimeter).
+ * `10 * INCH` in a script evaluates to `10 * 25.4 === 254` (plain JS multiply).
+ */
+export const SCRIPT_UNIT_CONSTANTS = Object.freeze({
+    MM: 1,
+    CM: 10,
+    METER: 1000,
+    MICRON: 0.001,
+    INCH: 25.4,
+    FOOT: 304.8,
+    YARD: 914.4,
+    DEGREE: 1,
+    RADIAN: 180 / Math.PI,
+    GRAM: 1,
+    KILOGRAM: 1000,
+    SECOND: 1,
+});
+/**
+ * Mapping from script-side unit constant names (UPPERCASE) to the internal
+ * `UnitName` (lowercase, used by UNIT_SCALE/UNIT_DIM for format-level units).
+ * Used by the dimension checker to resolve a script constant to its dimension.
+ */
+export const SCRIPT_UNIT_TO_NAME = Object.freeze({
+    MM: 'mm', CM: 'cm', METER: 'm', MICRON: 'micron',
+    INCH: 'inch', FOOT: 'foot', YARD: 'yard',
+    DEGREE: 'degree', RADIAN: 'radian',
+    GRAM: 'gram', KILOGRAM: 'kilogram',
+    SECOND: 'second',
+});
+/** The set of script-side unit constant names (for fast membership tests). */
+export const SCRIPT_UNIT_NAMES = new Set(Object.keys(SCRIPT_UNIT_CONSTANTS));
+// ── Typed constants (ValueWithUnits) ────────────────────────────────────────
+/** 1 mm — the base length unit. */
+export const mm = new ValueWithUnits(1, LENGTH);
+/** 1 cm = 10 mm. */
+export const centimeter = new ValueWithUnits(10, LENGTH);
+/** 1 m = 1000 mm. */
+export const meter = new ValueWithUnits(1000, LENGTH);
+/** 1 micron = 0.001 mm (one of the 3MF unit enum values). */
+export const micron = new ValueWithUnits(0.001, LENGTH);
+/** 1 inch = 25.4 mm. */
+export const inch = new ValueWithUnits(25.4, LENGTH);
+/** 1 foot = 304.8 mm. */
+export const foot = new ValueWithUnits(304.8, LENGTH);
+/** 1 yard = 914.4 mm. */
+export const yard = new ValueWithUnits(914.4, LENGTH);
+/** The base angle unit — 1 degree. */
+export const degree = new ValueWithUnits(1, ANGLE);
+/** 1 radian = 180/π degrees (base is degree). */
+export const radian = new ValueWithUnits(180 / Math.PI, ANGLE);
+/** 1 gram (base mass unit). */
+export const gram = new ValueWithUnits(1, MASS);
+/** 1 kilogram = 1000 gram. */
+export const kilogram = new ValueWithUnits(1000, MASS);
+/** 1 second (base time unit). */
+export const second = new ValueWithUnits(1, TIME);
+// ── Pure-number constants (number) = base-unit scale ────────────────────────
+// TS library code that calls geometric ops directly uses these bare numbers
+// (D4): `const L = 10 * INCH; cad.box({ size: [L, 20 * MM, 30 * MM] })`.
+/** 1 (mm). */
+export const MM = 1;
+/** 10 (mm). */
+export const CM = 10;
+/** 1000 (mm). */
+export const M = 1000;
+/** 0.001 (mm). */
+export const MICRON = 0.001;
+/** 25.4 (mm). */
+export const INCH = 25.4;
+/** 304.8 (mm). */
+export const FOOT = 304.8;
+/** 914.4 (mm). */
+export const YARD = 914.4;
+/** 1 (degree). */
+export const DEGREE = 1;
+/** 180/π (degree). */
+export const RADIAN = 180 / Math.PI;
+/** Base display units (mm / degree). */
+export const BASE_UNITS = Object.freeze({ length: 'mm', angle: 'degree' });
+/**
+ * The display unit for a dimension within a context. Only `length` and
+ * `angle` are host-settable; all other dimensions fall back to their base unit.
+ * @param dim - the dimension to look up.
+ * @param ctx - the system unit context; defaults to base units.
+ * @returns the unit name.
+ */
+export function unitFor(dim, ctx) {
+    if (dim === 'length' || dim === 'angle') {
+        return (ctx ?? BASE_UNITS)[dim];
+    }
+    // mass / temperature / time / current have no display override → their base.
+    switch (dim) {
+        case 'mass': return 'gram';
+        case 'temperature': return 'kelvin';
+        case 'time': return 'second';
+        case 'current': return 'ampere';
+        default: return 'mm';
+    }
+}
+/**
+ * Scale factor of a unit name relative to the base unit.
+ * @param name - the unit name.
+ * @returns the scale factor (e.g. `inch` → `25.4`).
+ */
+export function unitScale(name) {
+    return UNIT_SCALE[name];
+}
+/**
+ * Convert a value given in a display unit to the base-unit value.
+ * @param n - the value in `unitName`.
+ * @param unitName - the source unit.
+ * @param dimensionName - the dimension (for validation).
+ * @returns the base-unit (mm/degree/...) value.
+ */
+export function toBase(n, unitName, dimensionName) {
+    requireDim(unitName, dimensionName);
+    return n * UNIT_SCALE[unitName];
+}
+/**
+ * Convert a base-unit value into a display unit.
+ * @param base - the base-unit (mm/degree/...) value.
+ * @param unitName - the target unit.
+ * @param dimensionName - the dimension (for validation).
+ * @returns the value expressed in `unitName`.
+ */
+export function fromBase(base, unitName, dimensionName) {
+    requireDim(unitName, dimensionName);
+    return base / UNIT_SCALE[unitName];
+}
+/** Throw when a unit is not a member of a dimension. */
+function requireDim(unitName, dimensionName) {
+    if (UNIT_DIM[unitName] !== dimensionName) {
+        throw new Error(`[units] unit '${unitName}' is ${UNIT_DIM[unitName]}; expected ${dimensionName}`);
+    }
+}
+/**
+ * True when the value has dimension length.
+ * @param v - the value to check.
+ * @returns `true` if `v.spec` equals `LENGTH`.
+ */
+export function isLength(v) {
+    return unitEquals(v.spec, LENGTH);
+}
+/**
+ * True when the value has dimension angle.
+ * @param v - the value to check.
+ * @returns `true` if `v.spec` equals `ANGLE`.
+ */
+export function isAngle(v) {
+    return unitEquals(v.spec, ANGLE);
+}
+//# sourceMappingURL=units.js.map