@jarenjs/core 0.9.2 → 0.34.2

package/src/chunk.js

@@ -0,0 +1,159 @@
+//@ts-check
+/**
+ * Cutting text down to size: the four operations every consumer of a
+ * too-large value needs, in one place.
+ *
+ * They live together because they are one decision made four ways —
+ * *how much of this do I carry?* `sizeOf` answers what it costs,
+ * `excerpt` shows a line of it, `truncate` cuts it at a boundary and
+ * says so, and `chunkText` splits it into pieces that can each be
+ * carried, addressed and fetched on their own.
+ *
+ * Two rules hold across all four:
+ *
+ *  - **Characters, not bytes and not tokens.** Tokens are
+ *    provider-private and bytes depend on an encoding nobody has agreed
+ *    on at this layer; characters are deterministic, and a budget stated
+ *    in them holds exactly.
+ *  - **A cut is always visible.** `excerpt` appends an ellipsis and
+ *    `truncate` a named marker, so nothing downstream — a reader, a
+ *    model, a diff — mistakes a cut tail for the end of the content.
+ *
+ * Nothing here allocates a copy it does not return: `chunkText` slices,
+ * and a caller streaming a corpus can write each piece and drop it.
+ */
+
+/**
+ * The size of a value as the characters it will occupy in a request: a
+ * string is its own length, anything else is the length of its JSON
+ * encoding. That is the one size rule the suite budgets against — an
+ * agent's history budget, a slot's metadata, a digest's cap — and it is
+ * exact rather than an estimate, which is what makes those budgets hold
+ * to the character instead of approximately.
+ * @param {any} value
+ * @returns {number}
+ */
+export function sizeOf(value) {
+  return typeof value === 'string' ? value.length : JSON.stringify(value ?? null).length;
+}
+
+/**
+ * A one-line excerpt: whitespace collapsed to single spaces, trimmed,
+ * hard-capped, with an ellipsis when anything was dropped. Total over
+ * `null`/`undefined`/non-strings, because it is called on content a
+ * provider or a store may have left absent.
+ * @param {any} text
+ * @param {number} max - characters kept, before the ellipsis
+ * @returns {string}
+ */
+export function excerpt(text, max) {
+  const flat = String(text ?? '').replace(/\s+/g, ' ').trim();
+  return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}
+
+/**
+ * A hard cut with a named suffix, preserving newlines — what an
+ * oversized result or an over-long generated block is reduced to. The
+ * suffix is part of the contract: a cut that looked like an ending would
+ * be read as one.
+ * @param {string} text
+ * @param {number} max
+ * @param {string} [marker] - the suffix appended when a cut happened
+ * @returns {string}
+ */
+export function truncate(text, max, marker = '… [truncated]') {
+  return text.length > max ? `${text.slice(0, max)}${marker}` : text;
+}
+
+/**
+ * How a text is cut into pieces.
+ *
+ *  - `size` — fixed character windows. The only strategy that will split
+ *    a word, and the only one whose piece count is exactly predictable.
+ *  - `line` — whole lines, grouped up to `size`. A line longer than
+ *    `size` becomes its own oversized piece rather than being split:
+ *    breaking a line is the one thing a line strategy may not do.
+ *  - `separator` — units delimited by `separator` (paragraphs, records),
+ *    grouped up to `size`, separators preserved between units in a
+ *    piece. Same rule for an oversized unit.
+ *
+ * @typedef {'size' | 'line' | 'separator'} ChunkStrategy
+ */
+
+/**
+ * Split a text into addressable pieces.
+ *
+ * Deterministic and total: the same text and the same options always
+ * produce the same pieces, with the same offsets, which is what lets a
+ * caller name a piece by its index and re-derive that name later instead
+ * of storing a mapping. Empty text produces no pieces at all — an empty
+ * piece is not a thing anyone wants an address for.
+ *
+ * `overlap` (character strategy only) repeats the tail of each piece at
+ * the head of the next, so a match spanning a cut is still found whole
+ * in one piece. It costs storage proportional to `overlap / size` and is
+ * off by default.
+ *
+ * @param {string} text
+ * @param {{ strategy?: ChunkStrategy, size?: number, overlap?: number,
+ *   separator?: string }} [options]
+ * @returns {Array<{ index: number, start: number, end: number, text: string }>}
+ *   `start`/`end` are offsets into the original text, so a piece can be
+ *   located in the source it came from.
+ */
+export function chunkText(text, options = {}) {
+  const source = String(text ?? '');
+  const size = Math.max(1, Math.floor(options.size ?? 4000));
+  const strategy = options.strategy ?? 'size';
+  if (source.length === 0) return [];
+
+  if (strategy === 'size') {
+    const overlap = Math.max(0, Math.min(Math.floor(options.overlap ?? 0), size - 1));
+    /** @type {Array<{ index: number, start: number, end: number, text: string }>} */
+    const pieces = [];
+    const step = size - overlap;
+    for (let start = 0; start < source.length; start += step) {
+      const end = Math.min(source.length, start + size);
+      pieces.push({ index: pieces.length, start, end, text: source.slice(start, end) });
+      if (end === source.length) break;
+    }
+    return pieces;
+  }
+
+  // line and separator differ only in what a unit is and what joins two
+  // of them back together — one grouping loop, two vocabularies
+  const separator = strategy === 'line' ? '\n' : (options.separator ?? '\n\n');
+  return groupUnits(source, separator, size);
+}
+
+/**
+ * Group separator-delimited units into pieces of at most `size`
+ * characters, never splitting a unit. A unit longer than `size` is its
+ * own piece and is reported oversized by its length rather than being
+ * cut — the caller asked for units, and a cut unit is not one.
+ * @param {string} source
+ * @param {string} separator
+ * @param {number} size
+ */
+function groupUnits(source, separator, size) {
+  /** @type {Array<{ index: number, start: number, end: number, text: string }>} */
+  const pieces = [];
+  const step = separator.length;
+  let start = 0;
+  let cursor = 0;
+  while (cursor < source.length) {
+    const found = source.indexOf(separator, cursor);
+    const unitEnd = found === -1 ? source.length : found + step;
+    // close the current piece when this unit would overflow it, unless
+    // the piece is still empty (which is the oversized-unit case)
+    if (unitEnd - start > size && cursor > start) {
+      pieces.push({ index: pieces.length, start, end: cursor, text: source.slice(start, cursor) });
+      start = cursor;
+    }
+    cursor = unitEnd;
+  }
+  if (cursor > start) {
+    pieces.push({ index: pieces.length, start, end: cursor, text: source.slice(start, cursor) });
+  }
+  return pieces;
+}

package/src/color.js

@@ -0,0 +1,125 @@
+//@ts-check
+/**
+ * @file Pure color helpers — dependency-free numeric math over color
+ * strings, with no view or DOM knowledge. The one home for the suite's
+ * color primitives (currently the hex `#rrggbb` interpolation used by the
+ * calc surface shader).
+ */
+
+/**
+ * Linear-interpolate two `#rrggbb` hex colors channel-by-channel and
+ * return the result as `#rrggbb`. `t` is the blend factor (0 → `a`,
+ * 1 → `b`); values outside `[0, 1]` extrapolate.
+ *
+ * @param {string} a a `#rrggbb` hex color
+ * @param {string} b a `#rrggbb` hex color
+ * @param {number} t blend factor
+ * @returns {string} the interpolated `#rrggbb` color
+ */
+export function lerpColor(a, b, t) {
+  const pa = parseInt(a.slice(1), 16);
+  const pb = parseInt(b.slice(1), 16);
+  const ar = (pa >> 16) & 255, ag = (pa >> 8) & 255, ab = pa & 255;
+  const br = (pb >> 16) & 255, bg = (pb >> 8) & 255, bb = pb & 255;
+  const r = Math.round(ar + (br - ar) * t);
+  const g = Math.round(ag + (bg - ag) * t);
+  const bl = Math.round(ab + (bb - ab) * t);
+  return '#' + ((1 << 24) | (r << 16) | (g << 8) | bl).toString(16).slice(1);
+}
+
+/**
+ * WCAG relative luminance of a `#rrggbb` hex color: 0 for black, 1 for
+ * white. The sRGB channels are linearized (the 2.4-exponent transfer
+ * curve with its linear toe) and weighted per ITU-R BT.709. Use it to
+ * pick a legible ink over an arbitrary fill (light ink below ~0.4,
+ * dark ink above).
+ *
+ * @param {string} hex a `#rrggbb` hex color
+ * @returns {number} relative luminance in [0, 1]
+ */
+export function relativeLuminance(hex) {
+  const p = parseInt(hex.slice(1), 16);
+  const r = channel(((p >> 16) & 255) / 255);
+  const g = channel(((p >> 8) & 255) / 255);
+  const b = channel((p & 255) / 255);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/**
+ * Linearize one sRGB channel value in [0, 1].
+ * @param {number} c
+ * @returns {number}
+ */
+function channel(c) {
+  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+
+/** The designed inks, and the WCAG AA threshold for body text. */
+const INK_DARK = '#1f2020';
+const INK_LIGHT = '#ffffff';
+const AA_CONTRAST = 4.5;
+
+/**
+ * A legible ink for text set INSIDE a concrete fill: near-black on light
+ * fills, white on dark ones.
+ *
+ * Keyed off the fill's luminance, **not** the theme. That distinction is the
+ * whole point: a fill the author named is a constant, so it does not follow
+ * light/dark — and if the ink does, a light fill under a dark theme ends up
+ * with light text on it and the label disappears.
+ *
+ * The choice is made by comparing the two candidates' actual WCAG contrast
+ * rather than by a luminance threshold. A threshold is subtly wrong in the
+ * mid-tones: at 0.4 a fill like `#87b496` took dark ink and landed at 2.33:1,
+ * well under AA, because the crossover between the two inks is near 0.179 and
+ * not where a round number puts it. Picking the better of two is optimal by
+ * construction, so the worst case over the whole RGB cube is ~4.6:1 — which
+ * clears AA with nothing to tune.
+ * @param {string} fillHex - The `#rgb` or `#rrggbb` fill under the text
+ * @returns {string} `#1f2020` or `#ffffff`
+ */
+export function inkFor(fillHex) {
+  const fill = relativeLuminance(expandHex(fillHex));
+  const preferred = contrastOf(fill, relativeLuminance(INK_DARK))
+    >= contrastOf(fill, relativeLuminance(INK_LIGHT))
+    ? INK_DARK
+    : INK_LIGHT;
+  if (contrastOf(fill, relativeLuminance(preferred)) >= AA_CONTRAST)
+    return preferred;
+  // The designed near-black is softer than true black, and that softness
+  // costs contrast: against a mid-tone it bottoms out near 4.06:1, just under
+  // AA. Falling through to pure black or white for exactly those fills keeps
+  // the guarantee without making every other diagram harsher than it needs.
+  return fill > 0.1791 ? '#000000' : '#ffffff';
+}
+
+/**
+ * The WCAG contrast ratio between two relative luminances, from 1 (identical)
+ * to 21 (black on white).
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+export function contrastOf(a, b) {
+  const hi = a > b ? a : b;
+  const lo = a > b ? b : a;
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/**
+ * Whether a CSS color value is a concrete hex this module can reason about.
+ * A `var(...)`, a named color or a function is not: it may resolve to
+ * anything at paint time, so the caller must fall back to its theme.
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isHexColor(value) {
+  return typeof value === 'string' && /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(value.trim());
+}
+
+/** Expand `#abc` to `#aabbcc`; pass a 6-digit hex through. */
+function expandHex(hex) {
+  const h = hex.trim();
+  if (h.length !== 4) return h;
+  return '#' + h[1] + h[1] + h[2] + h[2] + h[3] + h[3];
+}

package/src/convert/convert.js

@@ -0,0 +1,59 @@
+//@ts-check
+/**
+ * @file The static conversion engine. Pure, single-pass,
+ * no per-call allocation. Rejects cross-dimension conversions with a
+ * clear error.
+ */
+
+import { DIMENSIONS, UNIT_INDEX } from './registry.js';
+
+/**
+ * Convert `value` from unit `fromId` to unit `toId` (same dimension).
+ * Affine through the dimension base: `base = value*factor + offset`,
+ * `target = (base - offset')/factor'`.
+ *
+ * @param {number} value
+ * @param {string} fromId
+ * @param {string} toId
+ * @returns {number}
+ */
+export function convert(value, fromId, toId) {
+  const from = UNIT_INDEX.get(fromId);
+  const to = UNIT_INDEX.get(toId);
+  if (from === undefined) throw new RangeError(`convert: unknown unit '${fromId}'`);
+  if (to === undefined) throw new RangeError(`convert: unknown unit '${toId}'`);
+  if (from.dimension !== to.dimension) {
+    throw new RangeError(
+      `convert: cannot convert '${fromId}' (${from.dimension}) to '${toId}' (${to.dimension})`);
+  }
+  const base = value * from.unit.factor + (from.unit.offset ?? 0);
+  return (base - (to.unit.offset ?? 0)) / to.unit.factor;
+}
+
+/**
+ * The unit list for a dimension (in registry order).
+ * @param {string} dimension
+ * @returns {import('./registry.js').Unit[]}
+ */
+export function unitsOf(dimension) {
+  const def = DIMENSIONS[dimension];
+  if (def === undefined) throw new RangeError(`convert: unknown dimension '${dimension}'`);
+  return def.units;
+}
+
+/**
+ * All dimension names.
+ * @returns {string[]}
+ */
+export function dimensions() {
+  return Object.keys(DIMENSIONS);
+}
+
+/**
+ * Look up the dimension a unit belongs to (or `null`).
+ * @param {string} unitId
+ * @returns {string|null}
+ */
+export function dimensionOf(unitId) {
+  return UNIT_INDEX.get(unitId)?.dimension ?? null;
+}

package/src/convert/currency.js

@@ -0,0 +1,74 @@
+//@ts-check
+/**
+ * @file The pure currency-conversion primitive.
+ * `convertCurrency` is deterministic and side-effect
+ * free: the caller supplies the `{ code: rate }` table; core NEVER
+ * fetches it. This lives in core because the dividing line is **purity**,
+ * not constant-vs-variable factors — this function is exactly as pure as
+ * the fixed-factor path, it just receives its factors as an argument.
+ * Fetching the table is the impure half and stays in the app component.
+ *
+ * Rate convention: `rateTable[code]` is the value of ONE unit of `code`
+ * expressed in the table's base currency (so the base currency has rate
+ * 1). To convert `value` from → to:
+ *
+ *   result = value * rate[from] / rate[to]
+ */
+
+/**
+ * @typedef {object} RateTable
+ * @property {string} [base] the base currency code (informational)
+ * @property {Record<string, number>} rates code → value-in-base
+ * @property {number|string} [at] timestamp of the table (informational)
+ */
+
+/**
+ * Resolve a rate for `code` from a table that may be either the
+ * `{ rates: {...} }` envelope or a bare `{ code: rate }` map.
+ * @param {RateTable | Record<string, number>} rateTable
+ * @param {string} code
+ * @returns {number|undefined}
+ */
+function rateFor(rateTable, code) {
+  if (rateTable && typeof rateTable === 'object' && 'rates' in rateTable
+    && rateTable.rates && typeof rateTable.rates === 'object') {
+    return /** @type {any} */ (rateTable).rates[code];
+  }
+  return /** @type {any} */ (rateTable)?.[code];
+}
+
+/**
+ * Convert an amount between currencies using a supplied rate table.
+ * Throws a `RangeError` when either code is missing from the table (the
+ * component decides how to fall back — a static table, a last-good cache).
+ *
+ * @param {number} value
+ * @param {string} from
+ * @param {string} to
+ * @param {RateTable | Record<string, number>} rateTable
+ * @returns {number}
+ */
+export function convertCurrency(value, from, to, rateTable) {
+  if (from === to) return value;
+  const rFrom = rateFor(rateTable, from);
+  const rTo = rateFor(rateTable, to);
+  if (typeof rFrom !== 'number' || !isFinite(rFrom)) {
+    throw new RangeError(`convertCurrency: no rate for '${from}'`);
+  }
+  if (typeof rTo !== 'number' || !isFinite(rTo) || rTo === 0) {
+    throw new RangeError(`convertCurrency: no rate for '${to}'`);
+  }
+  return (value * rFrom) / rTo;
+}
+
+/**
+ * The currency codes available in a rate table.
+ * @param {RateTable | Record<string, number>} rateTable
+ * @returns {string[]}
+ */
+export function currenciesOf(rateTable) {
+  const rates = (rateTable && typeof rateTable === 'object' && 'rates' in rateTable)
+    ? /** @type {any} */ (rateTable).rates
+    : rateTable;
+  return rates ? Object.keys(rates) : [];
+}

package/src/convert/index.js

@@ -0,0 +1,11 @@
+//@ts-check
+/**
+ * @file `@jarenjs/core/convert` — pure, deterministic quantity
+ * conversion. Fixed-factor dimensional conversion (`convert`) plus the
+ * pure rate-table primitive `convertCurrency` (the caller supplies the
+ * table; core never fetches). Zero runtime dependencies.
+ */
+
+export { DIMENSIONS, UNIT_INDEX } from './registry.js';
+export { convert, unitsOf, dimensions, dimensionOf } from './convert.js';
+export { convertCurrency, currenciesOf } from './currency.js';

package/src/convert/registry.js

@@ -0,0 +1,213 @@
+//@ts-check
+/**
+ * @file Unit registry. Fixed-factor unit definitions per
+ * **dimension**. Conversion is affine through the dimension's base unit:
+ *
+ *   base   = value * factor + offset
+ *   target = (base - offset') / factor'
+ *
+ * Most dimensions are linear (`offset` absent = 0); **temperature** is
+ * affine (°C/°F/K/°R). Digital storage ships both binary (KiB/MiB, 1024)
+ * and decimal (KB/MB, 1000) prefixes.
+ *
+ * Number-base conversion (HEX/DEC/OCT/BIN) is intentionally NOT here — it
+ * is `@jarenjs/core/math/word.js` (`toBase`/`fromBase`), which the
+ * converter delegates to. Fuel-economy (mpg ↔ L/100km) is non-affine and
+ * likewise out of this data-driven model.
+ */
+
+const F = 5 / 9; // °F/°R scale relative to Kelvin
+
+/**
+ * @typedef {object} Unit
+ * @property {string} id unique unit id
+ * @property {string} symbol display symbol
+ * @property {number} factor multiply to reach the base unit
+ * @property {number} [offset] affine offset toward the base unit
+ */
+
+/** @type {Record<string, { base: string, units: Unit[] }>} */
+export const DIMENSIONS = {
+  length: {
+    base: 'm',
+    units: [
+      { id: 'nm', symbol: 'nm', factor: 1e-9 },
+      { id: 'um', symbol: 'µm', factor: 1e-6 },
+      { id: 'mm', symbol: 'mm', factor: 0.001 },
+      { id: 'cm', symbol: 'cm', factor: 0.01 },
+      { id: 'm', symbol: 'm', factor: 1 },
+      { id: 'km', symbol: 'km', factor: 1000 },
+      { id: 'in', symbol: 'in', factor: 0.0254 },
+      { id: 'ft', symbol: 'ft', factor: 0.3048 },
+      { id: 'yd', symbol: 'yd', factor: 0.9144 },
+      { id: 'mi', symbol: 'mi', factor: 1609.344 },
+      { id: 'nmi', symbol: 'nmi', factor: 1852 },
+    ],
+  },
+  area: {
+    base: 'm2',
+    units: [
+      { id: 'mm2', symbol: 'mm²', factor: 1e-6 },
+      { id: 'cm2', symbol: 'cm²', factor: 1e-4 },
+      { id: 'm2', symbol: 'm²', factor: 1 },
+      { id: 'ha', symbol: 'ha', factor: 10000 },
+      { id: 'km2', symbol: 'km²', factor: 1e6 },
+      { id: 'in2', symbol: 'in²', factor: 0.00064516 },
+      { id: 'ft2', symbol: 'ft²', factor: 0.09290304 },
+      { id: 'acre', symbol: 'acre', factor: 4046.8564224 },
+      { id: 'mi2', symbol: 'mi²', factor: 2589988.110336 },
+    ],
+  },
+  volume: {
+    base: 'l',
+    units: [
+      { id: 'ml', symbol: 'mL', factor: 0.001 },
+      { id: 'l', symbol: 'L', factor: 1 },
+      { id: 'm3', symbol: 'm³', factor: 1000 },
+      { id: 'tsp', symbol: 'tsp', factor: 0.00492892159 },
+      { id: 'tbsp', symbol: 'tbsp', factor: 0.0147867648 },
+      { id: 'floz', symbol: 'fl oz', factor: 0.0295735296 },
+      { id: 'cup', symbol: 'cup', factor: 0.2365882365 },
+      { id: 'pt', symbol: 'pt', factor: 0.473176473 },
+      { id: 'qt', symbol: 'qt', factor: 0.946352946 },
+      { id: 'gal', symbol: 'gal', factor: 3.785411784 },
+    ],
+  },
+  mass: {
+    base: 'kg',
+    units: [
+      { id: 'mg', symbol: 'mg', factor: 1e-6 },
+      { id: 'g', symbol: 'g', factor: 0.001 },
+      { id: 'kg', symbol: 'kg', factor: 1 },
+      { id: 't', symbol: 't', factor: 1000 },
+      { id: 'oz', symbol: 'oz', factor: 0.028349523125 },
+      { id: 'lb', symbol: 'lb', factor: 0.45359237 },
+      { id: 'st', symbol: 'st', factor: 6.35029318 },
+    ],
+  },
+  temperature: {
+    base: 'K',
+    units: [
+      { id: 'K', symbol: 'K', factor: 1, offset: 0 },
+      { id: 'C', symbol: '°C', factor: 1, offset: 273.15 },
+      { id: 'F', symbol: '°F', factor: F, offset: 273.15 - 32 * F },
+      { id: 'R', symbol: '°R', factor: F, offset: 0 },
+    ],
+  },
+  time: {
+    base: 's',
+    units: [
+      { id: 'ns', symbol: 'ns', factor: 1e-9 },
+      { id: 'us', symbol: 'µs', factor: 1e-6 },
+      { id: 'ms', symbol: 'ms', factor: 0.001 },
+      { id: 's', symbol: 's', factor: 1 },
+      { id: 'min', symbol: 'min', factor: 60 },
+      { id: 'h', symbol: 'h', factor: 3600 },
+      { id: 'day', symbol: 'day', factor: 86400 },
+      { id: 'week', symbol: 'week', factor: 604800 },
+      { id: 'year', symbol: 'year', factor: 31557600 },
+    ],
+  },
+  speed: {
+    base: 'mps',
+    units: [
+      { id: 'mps', symbol: 'm/s', factor: 1 },
+      { id: 'kmh', symbol: 'km/h', factor: 1 / 3.6 },
+      { id: 'mph', symbol: 'mph', factor: 0.44704 },
+      { id: 'fps', symbol: 'ft/s', factor: 0.3048 },
+      { id: 'knot', symbol: 'kn', factor: 0.514444444 },
+    ],
+  },
+  pressure: {
+    base: 'pa',
+    units: [
+      { id: 'pa', symbol: 'Pa', factor: 1 },
+      { id: 'kpa', symbol: 'kPa', factor: 1000 },
+      { id: 'bar', symbol: 'bar', factor: 100000 },
+      { id: 'atm', symbol: 'atm', factor: 101325 },
+      { id: 'psi', symbol: 'psi', factor: 6894.757293168 },
+      { id: 'mmhg', symbol: 'mmHg', factor: 133.322387415 },
+      { id: 'torr', symbol: 'Torr', factor: 101325 / 760 },
+    ],
+  },
+  energy: {
+    base: 'j',
+    units: [
+      { id: 'j', symbol: 'J', factor: 1 },
+      { id: 'kj', symbol: 'kJ', factor: 1000 },
+      { id: 'cal', symbol: 'cal', factor: 4.184 },
+      { id: 'kcal', symbol: 'kcal', factor: 4184 },
+      { id: 'wh', symbol: 'Wh', factor: 3600 },
+      { id: 'kwh', symbol: 'kWh', factor: 3600000 },
+      { id: 'btu', symbol: 'BTU', factor: 1055.05585262 },
+      { id: 'ev', symbol: 'eV', factor: 1.602176634e-19 },
+    ],
+  },
+  power: {
+    base: 'w',
+    units: [
+      { id: 'w', symbol: 'W', factor: 1 },
+      { id: 'kw', symbol: 'kW', factor: 1000 },
+      { id: 'mw', symbol: 'MW', factor: 1e6 },
+      { id: 'hp', symbol: 'hp', factor: 745.699871582 },
+      { id: 'ps', symbol: 'PS', factor: 735.49875 },
+    ],
+  },
+  data: {
+    base: 'B',
+    units: [
+      { id: 'bit', symbol: 'bit', factor: 0.125 },
+      { id: 'B', symbol: 'B', factor: 1 },
+      { id: 'KB', symbol: 'KB', factor: 1e3 },
+      { id: 'MB', symbol: 'MB', factor: 1e6 },
+      { id: 'GB', symbol: 'GB', factor: 1e9 },
+      { id: 'TB', symbol: 'TB', factor: 1e12 },
+      { id: 'KiB', symbol: 'KiB', factor: 1024 },
+      { id: 'MiB', symbol: 'MiB', factor: 1048576 },
+      { id: 'GiB', symbol: 'GiB', factor: 1073741824 },
+      { id: 'TiB', symbol: 'TiB', factor: 1099511627776 },
+    ],
+  },
+  datarate: {
+    base: 'bps',
+    units: [
+      { id: 'bps', symbol: 'bit/s', factor: 1 },
+      { id: 'kbps', symbol: 'kbit/s', factor: 1e3 },
+      { id: 'mbps', symbol: 'Mbit/s', factor: 1e6 },
+      { id: 'gbps', symbol: 'Gbit/s', factor: 1e9 },
+      { id: 'Bps', symbol: 'B/s', factor: 8 },
+      { id: 'KBps', symbol: 'KB/s', factor: 8e3 },
+      { id: 'MBps', symbol: 'MB/s', factor: 8e6 },
+    ],
+  },
+  frequency: {
+    base: 'hz',
+    units: [
+      { id: 'hz', symbol: 'Hz', factor: 1 },
+      { id: 'khz', symbol: 'kHz', factor: 1e3 },
+      { id: 'mhz', symbol: 'MHz', factor: 1e6 },
+      { id: 'ghz', symbol: 'GHz', factor: 1e9 },
+    ],
+  },
+  angle: {
+    base: 'rad',
+    units: [
+      { id: 'rad', symbol: 'rad', factor: 1 },
+      { id: 'deg', symbol: '°', factor: Math.PI / 180 },
+      { id: 'grad', symbol: 'grad', factor: Math.PI / 200 },
+      { id: 'turn', symbol: 'turn', factor: 2 * Math.PI },
+    ],
+  },
+};
+
+/**
+ * Reverse index: unit id → `{ dimension, unit }`. Built once at module
+ * load; ids are unique across dimensions.
+ * @type {Map<string, { dimension: string, unit: Unit }>}
+ */
+export const UNIT_INDEX = new Map();
+for (const [dimension, def] of Object.entries(DIMENSIONS)) {
+  for (const unit of def.units) {
+    UNIT_INDEX.set(unit.id, { dimension, unit });
+  }
+}