gulp-mu-gulp-api 0.3.4 → 0.3.6

package/README.md

@@ -32,6 +32,11 @@ The module is deliberately **dependency-free** and knows nothing about µGulp™
 npm install gulp-mu-gulp-api
 ```
 
+### 0.3.5
+
+- **Added** `PlaySound(sample, { loop? })` and `StopSound(sample)` — play named samples from the dashboard µAU sound atlas; `loop: true` repeats until `StopSound`.
+- **Changed** npm README: clearer i18x section (`Log`/`Warn` vs `.i18xTrans()` / `.i18xRegister()`).
+
 ### 0.3.3
 
 - **Changed** npm README: centered µGulp logo and µGulp ready badge (absolute raw URLs from the µGulp repo).
@@ -50,7 +55,7 @@ npm install gulp-mu-gulp-api
 ## Usage
 
 ```javascript
-import { ReportProgress, CreateProgress, PlaySignal, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
+import { ReportProgress, CreateProgress, PlaySignal, PlaySound, StopSound, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
 
 // Enables "phrase<context=\"…\"/>".i18xRegister()/.i18xTrans() on strings.
 InstallStringExtensions();
@@ -77,7 +82,10 @@ export async function BUILD_THEME() {
     progress.Done();
 
     // sound + speech (rendered by the dashboard, configured in its settings)
-    PlaySignal('success');
+    PlaySignal('success');              // preset: success | error | attention
+    PlaySound('success');               // named atlas sample
+    PlaySound('engine', { loop: true }); // loop until StopSound('engine')
+    StopSound('engine');
     Speak('Theme build finished.');
 }
 BUILD_THEME.µDisplayName = 'Build Theme<context="µDisplayName"/>'.i18xRegister();
@@ -106,12 +114,16 @@ let values = await RequestForm({
 | :--- | :--- |
 | `IsMicroGulp()` / `IsµGulp()` | `true` when the task runs under µGulp™ with an attached dashboard |
 | `InstallStringExtensions()` | Installs µLib-compatible `String.prototype.i18xTrans()`/`i18xRegister()` (auto-run on import) |
-| `Log(text, values?)` / `Warn` / `LogError` | Localized `console.*` via i18x (`<context="task log"/>` etc.) |
-| `Translate(text, values?)` | Returns the translated string without logging |
+| `Log(text, values?)` / `Warn` / `LogError` | Localized `console.*` via i18x (`<context="task log"/>` etc.) — preferred for task log output |
+| `Translate(text, values?)` | Low-level: returns the translated string without logging (rarely needed directly) |
+| `"phrase".i18xTrans(values?)` | Prototype sugar for `Translate` — same result, ergonomic in expressions |
+| `"phrase".i18xRegister()` | Registers metadata text (returns the source phrase unchanged as the i18x key) |
 | `GetLid()` / `SetLid(lid?)` | Active language id; `SetLid` clears to automatic when omitted |
 | `ReportProgress(value, label?)` | Report progress `0..1` to the task progress bar |
 | `CreateProgress(label?)` | Reporter object with `Update(value, stepLabel?)` and `Done()` |
-| `PlaySignal(signal?)` | Acoustic signal in the dashboard: `'success'` \| `'error'` \| `'attention'` (default) |
+| `PlaySignal(signal?)` | Preset acoustic signal: `'success'` \| `'error'` \| `'attention'` (default) |
+| `PlaySound(sample, options?)` | Named sample from the dashboard sound atlas; `options.loop` repeats until `StopSound` |
+| `StopSound(sample)` | Stops a looping sample started with `PlaySound(sample, { loop: true })` |
 | `Speak(text, options?)` | Speech output in the dashboard; `options`: `{ rate?, pitch?, volume? }` per-call overrides |
 | `RequestForm(form)` | Request a complete form; resolves with `{ fieldId: value, … }` |
 | `RequestTextInput(options)` | Single text field (with `validate` rules) |
@@ -172,6 +184,7 @@ A field descriptor is `{ id, type, label, default?, options?, validate?, min?, m
 | :--- | :--- | :--- |
 | `ReportProgress` | updating progress line | log line every 10% step |
 | `PlaySignal` | terminal bell (`attention`/`error`) | silent |
+| `PlaySound` / `StopSound` | `[sound] <name>` log line | silent |
 | `Speak` | `[speech]` log line | `[speech]` log line |
 | text/password/number/range input | readline prompt (Enter = default) | default value |
 | font/select/radio input | numbered list + readline | default value |
@@ -183,6 +196,33 @@ Sound and speech playback (mute, volume, speech rate/pitch) is configured centra
 
 MIT — © 2026 Meinolf Amekudzi
 
+### Publishing (maintainers)
+
+npm accounts with 2FA reject `npm publish` with `EOTP` when `~/.npmrc` holds a
+web-login session token (`npm login --auth-type=web`). The reliable fix is a
+**Granular Access Token** with **Bypass 2FA** and **write** access to this package:
+
+1. npmjs.com → Access Tokens → Generate → Granular
+2. Permissions: **Read and write**, Packages: `gulp-mu-gulp-api` (or All packages)
+3. Enable **Bypass 2FA**, copy the token, then:
+
+```powershell
+npm config set //registry.npmjs.org/:_authToken <TOKEN>
+```
+
+After that, publish without any OTP:
+
+```powershell
+npm run publish:api
+```
+
+Bump `gulp-mu-gulp-api/package.json` before publishing. The task runs the module
+tests first. As a one-off, a 2FA code still works via `NPM_OTP`:
+
+```powershell
+$env:NPM_OTP="123456"; npm run publish:api
+```
+
 ---
 
 # Deutsch
@@ -199,6 +239,11 @@ Das Modul ist bewusst **abhängigkeitsfrei** und kennt keine µGulp™-Interna:
 npm install gulp-mu-gulp-api
 ```
 
+### 0.3.5
+
+- **Neu** `PlaySound(sample, { loop? })` und `StopSound(sample)` — benannte Samples aus dem Dashboard-µAU-Sound-Atlas; `loop: true` wiederholt bis `StopSound`.
+- **Geändert** npm-README: klarere i18x-Sektion (`Log`/`Warn` vs. `.i18xTrans()` / `.i18xRegister()`).
+
 ### 0.3.3
 
 - **Geändert** npm-README: zentriertes µGulp-Logo und µGulp-ready-Badge (absolute raw-URLs aus dem µGulp-Repo).
@@ -217,7 +262,7 @@ npm install gulp-mu-gulp-api
 ## Verwendung
 
 ```javascript
-import { ReportProgress, CreateProgress, PlaySignal, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
+import { ReportProgress, CreateProgress, PlaySignal, PlaySound, StopSound, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
 
 // Enables "phrase<context=\"…\"/>".i18xRegister()/.i18xTrans() on strings.
 InstallStringExtensions();
@@ -244,7 +289,10 @@ export async function BUILD_THEME() {
     progress.Done();
 
     // sound + speech (rendered by the dashboard, configured in its settings)
-    PlaySignal('success');
+    PlaySignal('success');              // preset: success | error | attention
+    PlaySound('success');               // named atlas sample
+    PlaySound('engine', { loop: true }); // loop until StopSound('engine')
+    StopSound('engine');
     Speak('Theme build finished.');
 }
 BUILD_THEME.µDisplayName = 'Build Theme<context="µDisplayName"/>'.i18xRegister();
@@ -273,12 +321,16 @@ let values = await RequestForm({
 | :--- | :--- |
 | `IsMicroGulp()` / `IsµGulp()` | `true`, wenn der Task unter µGulp™ mit angebundenem Dashboard läuft |
 | `InstallStringExtensions()` | Installiert µLib-kompatible `String.prototype.i18xTrans()`/`i18xRegister()` (läuft beim Import automatisch) |
-| `Log(text, values?)` / `Warn` / `LogError` | Lokalisierte `console.*`-Ausgabe über i18x (`<context="task log"/>` usw.) |
-| `Translate(text, values?)` | Gibt den übersetzten String zurück, ohne zu loggen |
+| `Log(text, values?)` / `Warn` / `LogError` | Lokalisierte `console.*`-Ausgabe über i18x — bevorzugt für Task-Logs |
+| `Translate(text, values?)` | Low-Level: übersetzter String ohne Log (selten direkt nötig) |
+| `"phrase".i18xTrans(values?)` | Prototype-Kurzform für `Translate` |
+| `"phrase".i18xRegister()` | Metadaten-Text registrieren (gibt die Quellphrase unverändert zurück) |
 | `GetLid()` / `SetLid(lid?)` | Aktive Sprach-ID; `SetLid` ohne Argument = automatische Auflösung |
 | `ReportProgress(value, label?)` | Fortschritt `0..1` an die Task-Progressbar melden |
 | `CreateProgress(label?)` | Reporter-Objekt mit `Update(value, stepLabel?)` und `Done()` |
-| `PlaySignal(signal?)` | Akustisches Signal im Dashboard: `'success'` \| `'error'` \| `'attention'` (Default) |
+| `PlaySignal(signal?)` | Vorgabe-Signal: `'success'` \| `'error'` \| `'attention'` (Default) |
+| `PlaySound(sample, options?)` | Benanntes Sample aus dem Sound-Atlas; `options.loop` wiederholt bis `StopSound` |
+| `StopSound(sample)` | Stoppt eine Schleife von `PlaySound(sample, { loop: true })` |
 | `Speak(text, options?)` | Sprachausgabe im Dashboard; `options`: `{ rate?, pitch?, volume? }` je Aufruf |
 | `RequestForm(form)` | Komplettes Formular anfordern; löst mit `{ fieldId: value, … }` auf |
 | `RequestTextInput(options)` | Einzelnes Textfeld (mit `validate`-Regeln) |
@@ -339,6 +391,7 @@ Ein Feld-Deskriptor ist `{ id, type, label, default?, options?, validate?, min?,
 | :--- | :--- | :--- |
 | `ReportProgress` | aktualisierende Fortschrittszeile | Log-Zeile je 10-%-Schritt |
 | `PlaySignal` | Terminal-Glocke (`attention`/`error`) | stumm |
+| `PlaySound` / `StopSound` | `[sound]`-Log-Zeile | stumm |
 | `Speak` | `[speech]`-Log-Zeile | `[speech]`-Log-Zeile |
 | Text-/Passwort-/Zahlen-/Range-Eingabe | readline-Prompt (Enter = Default) | Default-Wert |
 | Font-/Select-/Radio-Eingabe | nummerierte Liste + readline | Default-Wert |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gulp-mu-gulp-api",
-	"version": "0.3.4",
+	"version": "0.3.6",
 	"description": "Public task API for the µGulp orchestrator: progress reporting, sound signals, speech output, localized console output (i18x) and interactive UI inputs (text, password, number, textarea, color, font, select, radio, multi-select checkbox, range slider, date/time, file) from within gulp tasks — with graceful CLI fallbacks when running without µGulp.",
 	"type": "module",
 	"main": "src/index.mjs",

package/src/i18x-engine.mjs

@@ -0,0 +1,636 @@
+// ===========================================
+// i18x-engine.mjs — eval-free i18x runtime core
+// © 1996-2026 Meinolf Amekudzi
+// (published under MIT license)
+// ===========================================
+
+/**
+ * Dependency-free, eval-free implementation of the i18x rendering engine.
+ *
+ * This is a faithful port of the canonical i18x runtime (µLib `i18x.mjs` and
+ * the i18xe C# `i18x.Trans`/`CreateFormatPlaceholders`), rebuilt as a pure
+ * interpreter so it runs unchanged in a Node process and inside a
+ * Content-Security-Policy-restricted webview (no `eval`, no `new Function`).
+ *
+ * The engine renders the i18x XML notation:
+ *   - placeholder tags: `<name/>`, `<name format="int"/>`
+ *   - conditionals:     `<x if="0-">-</x>`, `<n if="1~">s</n>` (`if`/`ifnot`/`ifin`/`ifnotin`)
+ *   - inline formats:   `<format name="…" …>…</format>` (also nested)
+ *   - value transforms: `expression="=round(x*100)/100"`
+ *   - enumerations:     `<hour enumeration="AM|PM"/>`
+ *   - digit tags:       `<i0/>`…`<iN/>` (integer), `<f0/>`… (fixed fraction),
+ *                       `<g0/>` (grouped fraction), `<r0/>` (roman), `<i/>`/`<f/>` (whole part)
+ *   - date/time tags:   `<day/>`, `<month/>` (0-based), `<year/>`, `<hour/>`, `<minute/>`,
+ *                       `<second/>`, `<weekday/>` and their `utc…` variants
+ *   - entities:         `<lt/>`, `<gt/>`, `<space/>`, `<nbsp/>`, `<br/>`, `<newline/>`, …
+ *
+ * NOTE: The `<m…/>` (zero-cut fraction) tags render empty here, mirroring the
+ * canonical µLib runtime. They are slated for a rework together with the i18x
+ * format catalog; do not rely on `<m…/>` output until then.
+ *
+ * @module gulp-mu-gulp-api/i18x-engine
+ */
+
+// -------------------------------------------------
+// expression evaluator (recursive descent, no eval)
+// -------------------------------------------------
+
+const EXPRESSION_FUNCTIONS = {
+	abs: (_a) => Math.abs(_a),
+	acos: (_a) => Math.acos(_a),
+	asin: (_a) => Math.asin(_a),
+	atan: (_a) => Math.atan(_a),
+	atan2: (_a, _b) => Math.atan2(_a, _b),
+	ceil: (_a) => Math.ceil(_a),
+	ceiling: (_a) => Math.ceil(_a),
+	cos: (_a) => Math.cos(_a),
+	cosh: (_a) => Math.cosh(_a),
+	exp: (_a) => Math.exp(_a),
+	fact: (_a) => {
+		let n = Math.floor(_a);
+		if (n < 0) return NaN;
+		let result = 1;
+		for (let k = 2; k <= n; k++) result *= k;
+		return result;
+	},
+	floor: (_a) => Math.floor(_a),
+	frac: (_a) => _a - Math.trunc(_a),
+	int: (_a) => Math.trunc(_a),
+	ln: (_a) => Math.log(_a),
+	log: (_a, _b) => (_b === undefined ? Math.log10(_a) : Math.log(_a) / Math.log(_b)),
+	max: (..._args) => Math.max(..._args),
+	min: (..._args) => Math.min(..._args),
+	pow: (_a, _b) => Math.pow(_a, _b),
+	round: (_a) => Math.round(_a),
+	sign: (_a) => Math.sign(_a),
+	sin: (_a) => Math.sin(_a),
+	sinh: (_a) => Math.sinh(_a),
+	sqr: (_a) => _a * _a,
+	sqrt: (_a) => Math.sqrt(_a),
+	tan: (_a) => Math.tan(_a),
+	tanh: (_a) => Math.tanh(_a),
+	trunc: (_a) => Math.trunc(_a),
+};
+
+const EXPRESSION_CACHE = new Map();
+
+/** Tokenizes an i18x expression string into numbers, identifiers and operators. */
+function _TokenizeExpression(_source) {
+	let tokens = [];
+	let index = 0;
+	let length = _source.length;
+	while (index < length) {
+		let ch = _source[index];
+		if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
+			index++;
+			continue;
+		}
+		if ((ch >= '0' && ch <= '9') || ch === '.') {
+			let start = index;
+			while (index < length && ((_source[index] >= '0' && _source[index] <= '9') || _source[index] === '.')) index++;
+			tokens.push({ type: 'number', value: parseFloat(_source.slice(start, index)) });
+			continue;
+		}
+		if ((ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') || ch === '_') {
+			let start = index;
+			while (index < length && ((_source[index] >= 'a' && _source[index] <= 'z') || (_source[index] >= 'A' && _source[index] <= 'Z') || (_source[index] >= '0' && _source[index] <= '9') || _source[index] === '_')) index++;
+			tokens.push({ type: 'ident', value: _source.slice(start, index) });
+			continue;
+		}
+		tokens.push({ type: 'op', value: ch });
+		index++;
+	}
+	return tokens;
+}
+
+/**
+ * Evaluates an i18x `expression="…"` value against the bound variable `x`.
+ * The leading `=` (if present) is stripped. Supports `+ - * / %`, unary minus,
+ * parentheses and the math functions listed in EXPRESSION_FUNCTIONS.
+ * @param {string} _source expression source (with or without leading `=`)
+ * @param {number} _x value bound to the variable `x`
+ * @returns {number}
+ */
+export function EvalExpression(_source, _x) {
+	let source = String(_source);
+	if (source.charAt(0) === '=') source = source.slice(1);
+	let tokens = EXPRESSION_CACHE.get(source);
+	if (!tokens) {
+		tokens = _TokenizeExpression(source);
+		EXPRESSION_CACHE.set(source, tokens);
+	}
+	let position = 0;
+
+	function _Peek() { return tokens[position]; }
+	function _Next() { return tokens[position++]; }
+
+	function _ParsePrimary() {
+		let token = _Peek();
+		if (!token) return 0;
+		if (token.type === 'op' && token.value === '(') {
+			_Next();
+			let value = _ParseExpression();
+			if (_Peek() && _Peek().value === ')') _Next();
+			return value;
+		}
+		if (token.type === 'op' && token.value === '-') {
+			_Next();
+			return -_ParsePrimary();
+		}
+		if (token.type === 'op' && token.value === '+') {
+			_Next();
+			return _ParsePrimary();
+		}
+		if (token.type === 'number') {
+			_Next();
+			return token.value;
+		}
+		if (token.type === 'ident') {
+			_Next();
+			let name = token.value;
+			if (_Peek() && _Peek().value === '(') {
+				_Next();
+				let args = [];
+				if (!(_Peek() && _Peek().value === ')')) {
+					args.push(_ParseExpression());
+					while (_Peek() && _Peek().value === ',') {
+						_Next();
+						args.push(_ParseExpression());
+					}
+				}
+				if (_Peek() && _Peek().value === ')') _Next();
+				let fn = EXPRESSION_FUNCTIONS[name];
+				return fn ? Number(fn(...args)) : 0;
+			}
+			if (name === 'x') return Number(_x);
+			return 0;
+		}
+		_Next();
+		return 0;
+	}
+
+	function _ParseTerm() {
+		let value = _ParsePrimary();
+		while (_Peek() && _Peek().type === 'op' && (_Peek().value === '*' || _Peek().value === '/' || _Peek().value === '%')) {
+			let op = _Next().value;
+			let right = _ParsePrimary();
+			if (op === '*') value *= right;
+			else if (op === '/') value /= right;
+			else value %= right;
+		}
+		return value;
+	}
+
+	function _ParseExpression() {
+		let value = _ParseTerm();
+		while (_Peek() && _Peek().type === 'op' && (_Peek().value === '+' || _Peek().value === '-')) {
+			let op = _Next().value;
+			let right = _ParseTerm();
+			if (op === '+') value += right;
+			else value -= right;
+		}
+		return value;
+	}
+
+	let result = _ParseExpression();
+	return Number.isFinite(result) ? result : 0;
+}
+
+// -------------------------------------------------
+// roman numerals
+// -------------------------------------------------
+
+const ROMAN_TABLE = [
+	[1000, 'M'], [900, 'CM'], [500, 'D'], [400, 'CD'], [100, 'C'], [90, 'XC'],
+	[50, 'L'], [40, 'XL'], [10, 'X'], [9, 'IX'], [5, 'V'], [4, 'IV'], [1, 'I'],
+];
+
+/** Converts a non-negative integer to its Roman-numeral string. */
+export function ToRoman(_value) {
+	let n = Math.abs(Math.round(Number(_value) || 0));
+	let out = '';
+	for (let [amount, symbol] of ROMAN_TABLE) {
+		while (n >= amount) {
+			out += symbol;
+			n -= amount;
+		}
+	}
+	return out;
+}
+
+// -------------------------------------------------
+// format definitions
+// -------------------------------------------------
+
+/**
+ * Parses a `<format …>…</format>` definition into a reusable descriptor:
+ * name, attribute map, inner XML body and the pre-scanned maximum digit index
+ * per digit class (needed for the fill/padding logic).
+ * @param {string} _def full `<format …>…</format>` source
+ * @returns {{ name: string, attrs: object, xml: string, maxes: object, flags: object, hasDateTags: boolean }}
+ */
+export function ParseFormatDef(_def) {
+	let def = String(_def);
+	let start = def.indexOf('<format');
+	let headerEnd = def.indexOf('>', start);
+	let attrsText = def.slice(start + 7, headerEnd);
+	let bodyStart = headerEnd + 1;
+	let bodyEnd = def.lastIndexOf('</format>');
+	let xml = bodyEnd >= 0 ? def.slice(bodyStart, bodyEnd) : def.slice(bodyStart);
+	let attrs = _ParseAttributes(attrsText);
+	return {
+		name: attrs.name ?? '',
+		attrs,
+		xml,
+		maxes: _ScanDigitMaxes(xml),
+		hasDateTags: /<\/?(?:utc)?(?:day|month|year|hour|minute|second|millisecond|weekday|weekofyear|dayofyear|timezone)[\s/>]/.test(xml),
+	};
+}
+
+/** Parses an XML attribute list (`name="value" …`) into a plain object. */
+function _ParseAttributes(_attrsText) {
+	let attrs = {};
+	let regex = /([a-zA-Z_][a-zA-Z0-9_]*)\s*=\s*"([^"]*)"/g;
+	let match;
+	while ((match = regex.exec(_attrsText)) !== null) attrs[match[1]] = match[2];
+	return attrs;
+}
+
+/** Pre-scans a format body for the highest `<iN/>`, `<fN/>`, `<gN/>`, `<rN/>` index. */
+function _ScanDigitMaxes(_xml) {
+	let maxes = { i: 0, f: 0, g: 0, r: 0 };
+	let regex = /<([ifgr])(\d+)\s*\/?>/g;
+	let match;
+	while ((match = regex.exec(_xml)) !== null) {
+		let cls = match[1];
+		let idx = parseInt(match[2], 10);
+		if (idx + 1 > maxes[cls]) maxes[cls] = idx + 1;
+	}
+	return maxes;
+}
+
+/**
+ * Registers a `<format …>` definition into a name-keyed map.
+ * @param {Object<string, object>} _formats target map (mutated)
+ * @param {string} _def format source
+ * @param {boolean} [_onlyIfNotExists] keep an existing entry with the same name
+ */
+export function RegisterFormat(_formats, _def, _onlyIfNotExists) {
+	let parsed = ParseFormatDef(_def);
+	if (!parsed.name) return;
+	if (_onlyIfNotExists && Object.prototype.hasOwnProperty.call(_formats, parsed.name)) return;
+	_formats[parsed.name] = parsed;
+}
+
+// -------------------------------------------------
+// value decomposition (CreateFormatPlaceholders port)
+// -------------------------------------------------
+
+/** Builds the digit-fill array exactly as the canonical engine does. */
+function _BuildFill(_count, _chr, _maxNo) {
+	let ret = [];
+	if (_maxNo > 0) {
+		let maxNo = _maxNo > _count ? _count : _maxNo;
+		for (let n = 0; n < maxNo; n++) ret.push(_chr);
+		for (let n = maxNo; n < _count; n++) ret.push('');
+		ret.reverse();
+	} else {
+		for (let n = 0; n < _count; n++) ret.push(_chr);
+	}
+	return ret;
+}
+
+/** Applies a `0=零|1=一`-style digit replacement map to a numeric string. */
+function _ApplyDigitMap(_string, _digitsAttr) {
+	if (!_digitsAttr) return _string;
+	let map = {};
+	for (let pair of _digitsAttr.split('|')) {
+		let [key, value] = pair.split('=');
+		if (key !== undefined && value !== undefined) map[key] = value;
+	}
+	let out = '';
+	for (let ch of _string) out += Object.prototype.hasOwnProperty.call(map, ch) ? map[ch] : ch;
+	return out;
+}
+
+/**
+ * Decomposes a numeric value into the placeholder set consumed by a number
+ * format body: `x`, `xa`, whole-part `i`/`f`, indexed `i0…`, `f0…`, `g0…`,
+ * roman `r0…`.
+ */
+function _NumberPlaceholders(_value, _def) {
+	let attrs = _def.attrs;
+	let base = parseInt(attrs.base ?? '10', 10) || 10;
+	let value = Number(_value) || 0;
+	if (attrs.expression) value = EvalExpression(attrs.expression, value);
+	let xa = Math.abs(value);
+	let numericString = base === 10 ? xa.toString() : Math.trunc(xa).toString(base);
+	numericString = _ApplyDigitMap(numericString, attrs.digits);
+	let parts = numericString.split('.');
+	let intString = parts[0] ?? '';
+	let fracString = parts[1] ?? '';
+
+	let placeholders = { x: value, xa, i: intString, f: fracString };
+
+	let iMax = _def.maxes.i;
+	if (iMax > 0) {
+		let fill = _BuildFill(iMax, attrs.ifillchr ?? '', parseInt(attrs.ifillmax ?? '0', 10) || 0);
+		let digits = intString.split('').reverse().concat(fill);
+		for (let n = 0; n < iMax; n++) placeholders['i' + n] = digits[n] ?? '';
+	}
+
+	let fMax = _def.maxes.f;
+	if (fMax > 0) {
+		let fill = _BuildFill(fMax, attrs.ffillchr ?? '', parseInt(attrs.ffillmax ?? '0', 10) || 0);
+		let digits = fracString.split('').concat(fill);
+		for (let n = 0; n < fMax; n++) placeholders['f' + n] = digits[n] ?? '';
+	}
+
+	let gMax = _def.maxes.g;
+	if (gMax > 0) {
+		let fill = _BuildFill(gMax, attrs.gfillchr ?? '', parseInt(attrs.gfillmax ?? '0', 10) || 0);
+		let digits = fracString.split('').concat(fill);
+		for (let n = 0; n < gMax; n++) placeholders['g' + n] = digits[n] ?? '';
+	}
+
+	let rMax = _def.maxes.r;
+	if (rMax > 0) {
+		let roman = ToRoman(value).split('').reverse();
+		let fill = _BuildFill(rMax, attrs.rfillchr ?? '', parseInt(attrs.rfillmax ?? '0', 10) || 0);
+		let digits = roman.concat(fill);
+		for (let n = 0; n < rMax; n++) placeholders['r' + n] = digits[n] ?? '';
+	}
+
+	return placeholders;
+}
+
+const WALL_CLOCK_FORMATTERS = new Map();
+
+/** Extracts wall-clock components for a timestamp in a given IANA timezone. */
+function _WallClockParts(_timestampMs, _timeZone) {
+	let tz = _timeZone || 'UTC';
+	let formatter = WALL_CLOCK_FORMATTERS.get(tz);
+	if (!formatter) {
+		try {
+			formatter = new Intl.DateTimeFormat('en-US', {
+				timeZone: tz, hour12: false, weekday: 'short',
+				year: 'numeric', month: '2-digit', day: '2-digit',
+				hour: '2-digit', minute: '2-digit', second: '2-digit',
+			});
+		} catch {
+			formatter = new Intl.DateTimeFormat('en-US', {
+				hour12: false, weekday: 'short',
+				year: 'numeric', month: '2-digit', day: '2-digit',
+				hour: '2-digit', minute: '2-digit', second: '2-digit',
+			});
+		}
+		WALL_CLOCK_FORMATTERS.set(tz, formatter);
+	}
+	let values = {};
+	for (let part of formatter.formatToParts(new Date(Number(_timestampMs) || 0))) values[part.type] = part.value;
+	let weekdayIndex = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 }[values.weekday] ?? 0;
+	let hour = parseInt(values.hour, 10) % 24;
+	return {
+		day: parseInt(values.day, 10),
+		month: parseInt(values.month, 10) - 1,
+		year: parseInt(values.year, 10),
+		hour,
+		minute: parseInt(values.minute, 10),
+		second: parseInt(values.second, 10),
+		weekday: weekdayIndex,
+	};
+}
+
+/** Decomposes a timestamp into date/time placeholders (local tz + utc variants). */
+function _DatePlaceholders(_value, _timeZone) {
+	let ms = Number(_value) || 0;
+	let local = _WallClockParts(ms, _timeZone);
+	let utcDate = new Date(ms);
+	return {
+		day: local.day, month: local.month, year: local.year,
+		hour: local.hour, minute: local.minute, second: local.second,
+		weekday: local.weekday, millisecond: utcDate.getUTCMilliseconds(),
+		timezone: _timeZone || 'UTC',
+		utcday: utcDate.getUTCDate(), utcmonth: utcDate.getUTCMonth(), utcyear: utcDate.getUTCFullYear(),
+		utchour: utcDate.getUTCHours(), utcminute: utcDate.getUTCMinutes(), utcsecond: utcDate.getUTCSeconds(),
+		utcweekday: utcDate.getUTCDay(), utcmillisecond: utcDate.getUTCMilliseconds(),
+	};
+}
+
+// -------------------------------------------------
+// named-format rendering
+// -------------------------------------------------
+
+/**
+ * Formats a value with a named format definition.
+ * @param {number} _value
+ * @param {string} _formatName
+ * @param {object} _ctx render context `{ lid, timeZone, formats }`
+ * @returns {string}
+ */
+export function FormatValue(_value, _formatName, _ctx) {
+	let def = _ResolveFormat(_formatName, _ctx);
+	if (!def) return String(_value);
+	let placeholders = _NumberPlaceholders(_value, def);
+	if (def.hasDateTags) Object.assign(placeholders, _DatePlaceholders(_value, _ctx.timeZone), { x: Number(_value) || 0 });
+	return Trans(def.xml, placeholders, _ctx);
+}
+
+/** Resolves a format by name from the local defs, then the context registry. */
+function _ResolveFormat(_name, _ctx, _localFormats) {
+	if (_localFormats && Object.prototype.hasOwnProperty.call(_localFormats, _name)) return _localFormats[_name];
+	let formats = _ctx.formats;
+	if (formats && Object.prototype.hasOwnProperty.call(formats, _name)) return formats[_name];
+	return null;
+}
+
+// -------------------------------------------------
+// entity tags
+// -------------------------------------------------
+
+const ENTITY_TAGS = {
+	lt: '<', gt: '>', obrc: '{', cbrc: '}', brl: '\u25C4', brr: '\u25BA',
+	br: '<br/>', newline: '\n', slashnewline: '\\n', quot: '"', quote: '"',
+	squot: "'", apos: "'", singlequote: "'", space: ' ', whitespace: ' ',
+	amp: '&', nbsp: '\u00A0', tab: '\t', hyphen: '\u00AD', '-': '\u00AD',
+	newpage: '\u21A1',
+};
+
+// -------------------------------------------------
+// core interpreter (i18x.Trans port)
+// -------------------------------------------------
+
+/**
+ * Renders an i18x XML string against a placeholder set. This is the shared
+ * interpreter used both for translated phrases and for format bodies.
+ * @param {string} _text i18x XML source (already looked up / translated)
+ * @param {object} [_placeholders] values for `<name/>` tags
+ * @param {object} [_ctx] render context `{ lid, timeZone, formats }`
+ * @returns {string}
+ */
+export function Trans(_text, _placeholders, _ctx) {
+	if (_text == null) return '';
+	let text = String(_text);
+	if (text.indexOf('<') === -1) return text;
+
+	let placeholders = _placeholders ?? {};
+	let ctx = _ctx ?? { lid: 'en-US', timeZone: 'UTC', formats: {} };
+	let localFormats = null;
+
+	let tokens = ('<i18x>' + text + '</i18x>').split('<');
+	let level = 0;
+	let txts = [''];
+	let visibles = [true];
+	let length = tokens.length;
+
+	for (let i = 0; i < length; i++) {
+		let token = tokens[i];
+		let closeIndex = token.indexOf('>');
+		if (closeIndex === -1) {
+			txts[level] += token;
+			continue;
+		}
+
+		let trailing = token.slice(closeIndex + 1);
+		let isClosingTag = token.charAt(0) === '/';
+		let isClosedTag = token.charAt(closeIndex - 1) === '/';
+		let sliceStart = 0;
+		let sliceEnd = closeIndex;
+		if (isClosedTag) sliceEnd -= 1;
+		if (isClosingTag) { sliceStart = 1; sliceEnd -= 1; }
+
+		let head = token.slice(sliceStart, sliceEnd);
+		let spaceIndex = head.indexOf(' ');
+		let tag = spaceIndex === -1 ? head : head.slice(0, spaceIndex);
+		let attrs = spaceIndex === -1 ? {} : _ParseAttributes(head.slice(spaceIndex + 1));
+
+		// inline <format> definitions: collect the raw block (honoring nesting),
+		// register it locally and skip over it without rendering its body.
+		if (tag === 'format' && !isClosingTag && !isClosedTag) {
+			let depth = 1;
+			let j = i;
+			while (depth > 0 && ++j < length) {
+				let inner = tokens[j];
+				let innerClose = inner.indexOf('>');
+				if (innerClose === -1) continue;
+				let innerClosing = inner.charAt(0) === '/';
+				let innerClosed = inner.charAt(innerClose - 1) === '/';
+				let innerHead = inner.slice(innerClosing ? 1 : 0, innerClose);
+				let innerSpace = innerHead.indexOf(' ');
+				let innerTag = innerSpace === -1 ? innerHead.replace(/\/$/, '') : innerHead.slice(0, innerSpace);
+				if (innerTag === 'format') {
+					if (innerClosing) depth--;
+					else if (!innerClosed) depth++;
+				}
+			}
+			let defSource = '<' + tokens.slice(i, j + 1).join('<');
+			if (!localFormats) localFormats = Object.create(null);
+			RegisterFormat(localFormats, defSource, true);
+			if (j < length) txts[level] += tokens[j].slice(tokens[j].indexOf('>') + 1);
+			i = j;
+			continue;
+		}
+
+		let value = '';
+		let doInsertValue = false;
+
+		if (isClosingTag) {
+			level--;
+			txts[level] += visibles[level + 1] ? txts[level + 1] : '';
+			txts[level] += trailing;
+			continue;
+		} else if (isClosedTag) {
+			doInsertValue = true;
+		} else {
+			level++;
+			txts[level] = '';
+			visibles[level] = true;
+		}
+
+		if (Object.prototype.hasOwnProperty.call(placeholders, tag)) {
+			let raw = placeholders[tag];
+			value = raw instanceof Date ? raw.getTime() : raw;
+		}
+		if (Object.prototype.hasOwnProperty.call(ENTITY_TAGS, tag)) value = ENTITY_TAGS[tag];
+
+		// process attributes in document order: value, expression, format, enumeration, if.
+		for (let attrKey of Object.keys(attrs)) {
+			let attrValue = attrs[attrKey];
+			if (attrKey === 'value') {
+				value = attrValue;
+			} else if (attrKey === 'expression') {
+				value = EvalExpression(attrValue, Number(value) || 0);
+			} else if (attrKey === 'format') {
+				let def = _ResolveFormat(attrValue, ctx, localFormats);
+				if (def) {
+					let subContext = localFormats ? { ...ctx, formats: { ...(ctx.formats ?? {}), ...localFormats } } : ctx;
+					value = FormatValue(Number(value) || 0, attrValue, subContext);
+				} else {
+					value = '';
+				}
+			} else if (attrKey === 'enumeration') {
+				let options = attrValue.split('|');
+				let index = parseInt(value, 10);
+				value = Number.isFinite(index) && index >= 0 && index < options.length ? options[index] : '';
+			} else if (attrKey === 'if' || attrKey === 'ifnot' || attrKey === 'ifin' || attrKey === 'ifnotin') {
+				visibles[level] = _EvaluateCondition(value, attrValue, attrKey);
+			}
+		}
+
+		txts[level] += (doInsertValue ? value : '') + trailing;
+	}
+
+	// flush any levels left open by unbalanced tags (e.g. the malformed roman format).
+	while (level > 0) {
+		txts[level - 1] += visibles[level] ? txts[level] : '';
+		level--;
+	}
+
+	return txts[0].replace(/\0/g, '');
+}
+
+/** Evaluates an `if`/`ifnot`/`ifin`/`ifnotin` condition against a value. */
+function _EvaluateCondition(_value, _condition, _attrKey) {
+	let numeric = Number(_value);
+	let isNumber = _value !== '' && _value !== null && Number.isFinite(numeric);
+	let compareNumber = isNumber ? numeric : NaN;
+	let compareString = String(_value);
+	let isIn = _attrKey === 'ifin' || _attrKey === 'ifnotin';
+
+	let matched = false;
+	for (let clause of _condition.split('|')) {
+		let operator = clause.charAt(clause.length - 1);
+		let operand = clause;
+		if (operator === '+' || operator === '-' || operator === '=' || operator === '~' || operator === '*') {
+			operand = clause.slice(0, -1);
+		} else {
+			operator = '';
+		}
+		let operandNumber = Number(operand);
+		let operandIsNumber = operand !== '' && Number.isFinite(operandNumber);
+
+		if (isNumber && operandIsNumber) {
+			if (operator === '+') matched = matched || compareNumber > operandNumber;
+			else if (operator === '-') matched = matched || compareNumber < operandNumber;
+			else if (operator === '=') matched = matched || compareNumber === operandNumber;
+			else if (operator === '~') matched = matched || compareNumber !== operandNumber;
+			else if (operator === '*') matched = matched || compareString.indexOf(operand) >= 0;
+			else matched = matched || compareNumber === operandNumber;
+		} else {
+			if (operator === '+') matched = matched || compareString > operand;
+			else if (operator === '-') matched = matched || compareString < operand;
+			else if (operator === '=') matched = matched || compareString === operand;
+			else if (operator === '~') matched = matched || compareString !== operand;
+			else if (operator === '*') matched = matched || compareString.indexOf(operand) >= 0;
+			else if (isIn) matched = matched || compareString.indexOf(operand) >= 0;
+			else matched = matched || compareString === operand;
+		}
+	}
+	if (_attrKey === 'ifnot' || _attrKey === 'ifnotin') matched = !matched;
+	return matched;
+}
+
+/** Removes any remaining i18x/XML tags from a string (after placeholder substitution). */
+export function StripTags(_text) {
+	return String(_text).replace(/<[^>]*>/g, '');
+}

package/src/i18x.mjs

@@ -31,6 +31,7 @@
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { Trans as EngineTrans, FormatValue as EngineFormatValue, RegisterFormat } from './i18x-engine.mjs';
 
 const DEFAULT_LID = 'en-US';
 
@@ -51,6 +52,7 @@ const LIDS_MAIN_CULTURES = {
 
 let dictionaryCache = new Map();
 let formatDefinitionCache = new Map();
+let formatRegistryCache = new Map();
 let availableLids = null;
 let activeLid = null;
 const timeZoneFormatters = {};
@@ -177,6 +179,7 @@ export function GetLid() {
 export function SetLid(_lid) {
 	activeLid = _lid ? _BestAvailableLid(_lid, _AvailableLids()) : null;
 	formatDefinitionCache.clear();
+	formatRegistryCache.clear();
 }
 
 /** Loads and caches `<dir>/<lid>.json`; a missing/broken file yields source text. */
@@ -215,90 +218,42 @@ function _LoadFormatDefinitions(_lid) {
 	return formats;
 }
 
-/** Formats milliseconds as M:SS or H:MM:SS (progress bar durations). */
-function _FormatDuration(_ms) {
-	let ms = Math.max(0, Number(_ms) || 0);
-	let totalSeconds = Math.round(ms / 1000);
-	let seconds = totalSeconds % 60;
-	let minutes = Math.floor(totalSeconds / 60) % 60;
-	let hours = Math.floor(totalSeconds / 3600);
-	let pad = (_n) => String(_n).padStart(2, '0');
-	return hours > 0 ? hours + ':' + pad(minutes) + ':' + pad(seconds) : minutes + ':' + pad(seconds);
+/** Builds (and caches) the name→parsed-definition format registry for a language. */
+function _FormatRegistry(_lid) {
+	if (formatRegistryCache.has(_lid)) return formatRegistryCache.get(_lid);
+	let registry = Object.create(null);
+	let definitions = _LoadFormatDefinitions(_lid);
+	for (let xml of Object.values(definitions)) RegisterFormat(registry, xml, false);
+	formatRegistryCache.set(_lid, registry);
+	return registry;
+}
+
+/** Assembles the engine render context (language, timezone, format registry). */
+function _RenderContext(_lid) {
+	let lid = _lid ?? GetLid();
+	return { lid, timeZone: GetTimeZone(), formats: _FormatRegistry(lid) };
 }
 
 /**
- * Formats a numeric value with a named i18xe format definition from the
- * project's i18x/gulp dictionaries (synced from i18xe prod).
+ * Formats a numeric/date value with a named i18xe format definition from the
+ * project's i18x/gulp dictionaries (synced from i18xe prod). Delegates to the
+ * eval-free i18x engine, so the full i18x notation (fill/padding, `if`
+ * conditions, nested formats, expressions, enumerations, date parts) is honored.
  * @param {number|string} _value
- * @param {string} _formatName e.g. 'int', 'floatFix2', 'byteSize'
+ * @param {string} _formatName e.g. 'int', 'floatFix2', 'byteSize', 'stdDateTime'
  * @param {string} [_lid]
  * @returns {string}
  */
 export function FormatValue(_value, _formatName, _lid) {
-	let lid = _lid ?? GetLid();
-	let tz = GetTimeZone();
-	if (_formatName === 'progressDuration') return _FormatDuration(Number(_value));
-	if (_formatName === 'stdTime') {
-		let date = new Date(Number(_value) || 0);
-		try {
-			return new Intl.DateTimeFormat(lid, { hour: '2-digit', minute: '2-digit', timeZone: tz }).format(date);
-		} catch {
-			return date.toISOString();
-		}
-	}
-	if (_formatName === 'stdDateTime' || _formatName === 'fullDateTime') {
-		let date = new Date(Number(_value) || 0);
-		try {
-			return new Intl.DateTimeFormat(lid, {
-				year: 'numeric', month: '2-digit', day: '2-digit',
-				hour: '2-digit', minute: '2-digit', timeZone: tz,
-			}).format(date);
-		} catch {
-			return date.toISOString();
-		}
-	}
-	if (_formatName === 'byteSize') {
-		let bytes = Number(_value);
-		if (!Number.isFinite(bytes)) return String(_value);
-		if (bytes >= 1073741824) return FormatValue(bytes / 1073741824, 'floatFix2', lid) + ' GB';
-		if (bytes >= 1048576) return FormatValue(bytes / 1048576, 'floatFix2', lid) + ' MB';
-		if (bytes >= 1024) return FormatValue(bytes / 1024, 'floatFix2', lid) + ' KB';
-		return FormatValue(bytes, 'int', lid) + ' Bytes';
-	}
-	let number = Number(_value);
-	if (!Number.isFinite(number)) return String(_value);
-	let definition = _LoadFormatDefinitions(lid)[_formatName];
-	if (!definition) return String(_value);
-	let groupSeparator = definition.match(/<xa if="1000\|1000\+">([^<]*)<\/xa>/)?.[1] ?? ',';
-	let decimalSeparator = definition.match(/if="0~">([^<]*)<m0\/>/)?.[1]
-		?? definition.match(/<\/xa>([^<]*)<f0\/>/)?.[1] ?? '.';
-	let fractionDigits = _formatName === 'floatFix1' ? 1
-		: (_formatName.startsWith('floatFix') ? 2 : 0);
-	if (_formatName === 'int') number = Math.round(number);
-	let negative = number < 0;
-	let absolute = Math.abs(number);
-	let integerPart = String(Math.trunc(fractionDigits ? absolute : Math.round(absolute)));
-	let grouped = integerPart.replace(/\B(?=(\d{3})+(?!\d))/g, groupSeparator);
-	let fraction = fractionDigits ? decimalSeparator + absolute.toFixed(fractionDigits).split('.')[1] : '';
-	return (negative ? '-' : '') + grouped + fraction;
-}
-
-/** Substitutes `<name/>` placeholders; honors `format="…"` via FormatValue. */
-function _ApplyPlaceholders(_text, _values) {
-	let text = String(_text);
-	let lid = GetLid();
-	for (let key of Object.keys(_values ?? {})) {
-		let pattern = new RegExp('<' + key + '(?:\\s+format="([^"]*)")?\\s*/>', 'g');
-		text = text.replace(pattern, (_match, _formatName) =>
-			_formatName ? FormatValue(_values[key], _formatName, lid) : String(_values[key]));
-	}
-	return text.replace(/<[^>]*>/g, '');
+	let context = _RenderContext(_lid);
+	if (!Object.prototype.hasOwnProperty.call(context.formats, _formatName)) return String(_value);
+	return EngineFormatValue(_value, _formatName, context);
 }
 
 /**
  * Translates a source phrase (including its context tag) into the active
- * language and resolves placeholders. Unknown phrases fall back to the en-US
- * source text with its tags stripped.
+ * language and renders it through the i18x engine (placeholders, `format="…"`,
+ * `if` conditions, …). Unknown phrases fall back to the en-US source text.
  * @param {string} _text source phrase, e.g. 'Build ready<context="task log"/>'
  * @param {object} [_values] placeholder values for `<name/>` tags
  * @returns {string}
@@ -309,7 +264,9 @@ export function Translate(_text, _values) {
 	let lid = GetLid();
 	let dictionary = lid === DEFAULT_LID ? null : _LoadDictionary(lid);
 	let translated = (dictionary && Object.prototype.hasOwnProperty.call(dictionary, source)) ? dictionary[source] : source;
-	return _ApplyPlaceholders(translated, _values);
+	// The context tag is part of the dictionary key only; strip it before rendering.
+	translated = translated.replace(/<context=[^>]*>/g, '');
+	return EngineTrans(translated, _values ?? {}, _RenderContext(lid));
 }
 
 /**

package/src/index.mjs

@@ -228,6 +228,48 @@ export function PlaySignal(_signal = 'attention') {
 	}
 }
 
+/**
+ * Plays a named sample from the dashboard sound atlas (µAU). Sample names match
+ * the files bundled with µGulp (`success`, `error`, `attention`, or custom
+ * atlas entries in the consumer skin). When `loop` is true the sample repeats
+ * until `StopSound(sample)` is called.
+ *
+ * CLI fallback: logs `[sound] <name>` on a TTY, silent otherwise.
+ *
+ * @param {string} _sample atlas sample name (e.g. `'success'`)
+ * @param {object} [_options]
+ * @param {boolean} [_options.loop] repeat until stopped (default `false`)
+ */
+export function PlaySound(_sample, _options = {}) {
+	let sample = String(_sample ?? '').trim();
+	if (!sample) return;
+	if (IsMicroGulp()) {
+		process.send({ type: 'sound', sample, loop: !!_options.loop });
+		return;
+	}
+	if (process.stdout.isTTY) {
+		console.log(`[sound] ${sample}${_options.loop ? ' (loop)' : ''}`);
+	}
+}
+
+/**
+ * Stops a looping sample started with `PlaySound(name, { loop: true })`.
+ * No-op for one-shot samples and outside µGulp (CLI logs `[sound-stop]` on TTY).
+ *
+ * @param {string} _sample atlas sample name passed to `PlaySound`
+ */
+export function StopSound(_sample) {
+	let sample = String(_sample ?? '').trim();
+	if (!sample) return;
+	if (IsMicroGulp()) {
+		process.send({ type: 'sound-stop', sample });
+		return;
+	}
+	if (process.stdout.isTTY) {
+		console.log(`[sound-stop] ${sample}`);
+	}
+}
+
 /**
  * Speaks a text through the µGulp dashboard speech output (Web Speech API,
  * respects the dashboard speech settings: enabled/volume/rate/pitch).
@@ -517,6 +559,8 @@ export default {
 	ReportProgress,
 	CreateProgress,
 	PlaySignal,
+	PlaySound,
+	StopSound,
 	Speak,
 	RequestForm,
 	RequestTextInput,