gulp-mu-gulp-api 0.3.6 → 0.3.8

package/README.md

@@ -32,6 +32,25 @@ The module is deliberately **dependency-free** and knows nothing about µGulp™
 npm install gulp-mu-gulp-api
 ```
 
+### 0.3.8
+
+- **Added** structured log elements rendered directly in the run log (JSON payloads, Content-Security-Policy safe, no plugin/iframe needed): `LogCallout()` (info/success/warning/error box), `LogKeyValue()` (metrics/summary list), `LogBadges()` (status chips), `LogCode()` (monospace code block) and `LogChart()` (inline-SVG bar chart).
+- Each new helper degrades to a readable stdout fallback when running outside µGulp (bracketed callout, aligned key/value lines, bracketed badges, verbatim code, ASCII bar chart).
+
+### 0.3.7
+
+- **Added** engine date/time placeholders: `weekofyear`, `dayofyear`, `utcweekofyear`, `utcdayofyear`, `timezoneoffset`, `timezoneshort`, `timezoneplace`.
+- **Added** `TimeZoneOffset()` — JavaScript-compatible offset in minutes (same sign as `Date.getTimezoneOffset()`).
+- **Added** hyphenation API: `WordHyphenation()`, `Hyphenation()`, `LoadHyphenData()`, `InstallHyphenPrototypes()` with µLib (`WordHyphenation`/`Hyphenation`) and i18xe-sync (`wordHyphenation`/`hyphenation`) aliases; without `<lid>.hyphen.json` data the methods no-op.
+- **Added** i18xe-sync lowercase format aliases: `Number.prototype.format()` / `.formatTimestamp()` / `.formatTicks()`, `Date.prototype.format()`.
+- **Changed** `Translate(text, values?, timeZone?)` and `.i18xTrans(values?, timeZone?)` accept an optional IANA timezone override.
+
+### 0.3.6
+
+- **Added** full eval-free i18x engine (`i18x-engine.mjs`): `FormatValue()`/`Translate()` now honor the complete i18x notation — `if`/`ifnot`/`ifin` conditions, nested formats, `expression="…"`, enumerations, digit fill/padding, date/time parts and roman numerals.
+- **Added** µLib-compatible `Number.prototype.Format()`, `Number.prototype.FormatTimestamp()`, `Number.prototype.FormatTicks()`, `Date.prototype.Format()` and `String.prototype.Format()` (installed automatically on import; see `InstallFormatPrototypes()`).
+- **Changed** `FormatValue(value, format, lid?, timeZone?)` gained the optional `timeZone` argument; date/time formats interpret the value as Unix milliseconds.
+
 ### 0.3.5
 
 - **Added** `PlaySound(sample, { loop? })` and `StopSound(sample)` — play named samples from the dashboard µAU sound atlas; `loop: true` repeats until `StopSound`.
@@ -113,9 +132,12 @@ let values = await RequestForm({
 | Function | Purpose |
 | :--- | :--- |
 | `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) |
+| `InstallStringExtensions()` | Installs µLib-compatible `String.prototype.i18xTrans()`/`i18xRegister()` and the Format prototypes (auto-run on import) |
+| `InstallFormatPrototypes()` | Installs `Number`/`Date`/`String.prototype.Format()` (auto-run on import) |
 | `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) |
+| `FormatValue(value, format, lid?, timeZone?)` | Formats a number/date with a named i18x format (`int`, `floatFix2`, `byteSize`, `stdDateTime`, …) |
+| `(1536).Format('byteSize')` | Prototype sugar for `FormatValue`; `.FormatTimestamp()`/`.FormatTicks()` on numbers, `.Format()` on dates |
 | `"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 |
@@ -239,6 +261,25 @@ Das Modul ist bewusst **abhängigkeitsfrei** und kennt keine µGulp™-Interna:
 npm install gulp-mu-gulp-api
 ```
 
+### 0.3.8
+
+- **Neu** strukturierte Log-Elemente, die direkt im Run-Log gerendert werden (JSON-Payloads, Content-Security-Policy-sicher, ohne Plugin/iframe): `LogCallout()` (Info/Success/Warning/Error-Box), `LogKeyValue()` (Metriken/Zusammenfassung), `LogBadges()` (Status-Chips), `LogCode()` (Monospace-Codeblock) und `LogChart()` (Inline-SVG-Balkendiagramm).
+- Jeder neue Helfer fällt außerhalb von µGulp auf eine lesbare stdout-Ausgabe zurück (Callout in Klammern, ausgerichtete Key/Value-Zeilen, Badges in Klammern, Code wortgetreu, ASCII-Balkendiagramm).
+
+### 0.3.7
+
+- **Neu** Engine-Datum/Zeit-Platzhalter: `weekofyear`, `dayofyear`, `utcweekofyear`, `utcdayofyear`, `timezoneoffset`, `timezoneshort`, `timezoneplace`.
+- **Neu** `TimeZoneOffset()` — JavaScript-kompatibler Offset in Minuten (gleiches Vorzeichen wie `Date.getTimezoneOffset()`).
+- **Neu** Silbentrennungs-API: `WordHyphenation()`, `Hyphenation()`, `LoadHyphenData()`, `InstallHyphenPrototypes()` mit µLib- (`WordHyphenation`/`Hyphenation`) und i18xe-sync-Aliasen (`wordHyphenation`/`hyphenation`); ohne `<lid>.hyphen.json`-Daten No-op.
+- **Neu** i18xe-sync-Lowercase-Format-Aliase: `Number.prototype.format()` / `.formatTimestamp()` / `.formatTicks()`, `Date.prototype.format()`.
+- **Geändert** `Translate(text, values?, timeZone?)` und `.i18xTrans(values?, timeZone?)` akzeptieren optional eine IANA-Zeitzone.
+
+### 0.3.6
+
+- **Neu** vollständige eval-freie i18x-Engine (`i18x-engine.mjs`): `FormatValue()`/`Translate()` beherrschen jetzt die komplette i18x-Notation — `if`/`ifnot`/`ifin`-Bedingungen, verschachtelte Formate, `expression="…"`, Enumerationen, Ziffern-Fill/Padding, Datum/Zeit-Teile und römische Zahlen.
+- **Neu** µLib-kompatible `Number.prototype.Format()`, `Number.prototype.FormatTimestamp()`, `Number.prototype.FormatTicks()`, `Date.prototype.Format()` und `String.prototype.Format()` (werden beim Import automatisch installiert; siehe `InstallFormatPrototypes()`).
+- **Geändert** `FormatValue(value, format, lid?, timeZone?)` um das optionale `timeZone`-Argument erweitert; Datum/Zeit-Formate interpretieren den Wert als Unix-Millisekunden.
+
 ### 0.3.5
 
 - **Neu** `PlaySound(sample, { loop? })` und `StopSound(sample)` — benannte Samples aus dem Dashboard-µAU-Sound-Atlas; `loop: true` wiederholt bis `StopSound`.
@@ -320,7 +361,10 @@ let values = await RequestForm({
 | Funktion | Zweck |
 | :--- | :--- |
 | `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) |
+| `InstallStringExtensions()` | Installiert µLib-kompatible `String.prototype.i18xTrans()`/`i18xRegister()` und die Format-Prototypes (läuft beim Import automatisch) |
+| `InstallFormatPrototypes()` | Installiert `Number`/`Date`/`String.prototype.Format()` (läuft beim Import automatisch) |
+| `FormatValue(value, format, lid?, timeZone?)` | Formatiert Zahl/Datum mit einem benannten i18x-Format (`int`, `floatFix2`, `byteSize`, `stdDateTime`, …) |
+| `(1536).Format('byteSize')` | Prototype-Kurzform für `FormatValue`; `.FormatTimestamp()`/`.FormatTicks()` an Zahlen, `.Format()` an Dates |
 | `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` |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gulp-mu-gulp-api",
-	"version": "0.3.6",
+	"version": "0.3.8",
 	"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

@@ -243,7 +243,7 @@ export function ParseFormatDef(_def) {
 		attrs,
 		xml,
 		maxes: _ScanDigitMaxes(xml),
-		hasDateTags: /<\/?(?:utc)?(?:day|month|year|hour|minute|second|millisecond|weekday|weekofyear|dayofyear|timezone)[\s/>]/.test(xml),
+		hasDateTags: /<\/?(?:utc)?(?:day|month|year|hour|minute|second|millisecond|weekday|weekofyear|dayofyear|timezone(?:offset|short|place)?|summertimeoffset)[\s/>]/.test(xml),
 	};
 }
 
@@ -401,19 +401,80 @@ function _WallClockParts(_timestampMs, _timeZone) {
 	};
 }
 
+/** ISO-8601 week number (1..53) for a calendar date (month is 0-based). */
+function _IsoWeekOfYear(_year, _month, _day) {
+	let d = new Date(Date.UTC(_year, _month, _day));
+	let dayOfWeek = d.getUTCDay();
+	if (dayOfWeek === 0) dayOfWeek = 7;
+	d.setUTCDate(d.getUTCDate() + 4 - dayOfWeek);
+	let yearStart = Date.UTC(d.getUTCFullYear(), 0, 1);
+	return Math.ceil(((d.getTime() - yearStart) / 86400000 + 1) / 7);
+}
+
+/** Day of year (1..366) for a calendar date (month is 0-based). */
+function _DayOfYear(_year, _month, _day) {
+	let start = Date.UTC(_year, 0, 1);
+	let current = Date.UTC(_year, _month, _day);
+	return Math.floor((current - start) / 86400000) + 1;
+}
+
+/** JavaScript-compatible getTimezoneOffset (minutes to add to local time to get UTC). */
+function _TimeZoneOffsetJsMinutes(_ms, _timeZone) {
+	let ms = Number(_ms) || 0;
+	let local = _WallClockParts(ms, _timeZone);
+	let utcDate = new Date(ms);
+	let wallAsUTC = Date.UTC(
+		local.year, local.month, local.day,
+		local.hour, local.minute, local.second, utcDate.getUTCMilliseconds(),
+	);
+	return Math.round((ms - wallAsUTC) / 60000);
+}
+
+const TIME_ZONE_SHORT_FORMATTERS = new Map();
+
+/** Best-effort timezone abbreviation via Intl (no TZNames database). */
+function _TimeZoneShort(_ms, _timeZone, _lid) {
+	let key = (_lid || 'en-US') + '\0' + (_timeZone || 'UTC');
+	let formatter = TIME_ZONE_SHORT_FORMATTERS.get(key);
+	if (!formatter) {
+		try {
+			formatter = new Intl.DateTimeFormat(_lid || 'en-US', { timeZone: _timeZone || 'UTC', timeZoneName: 'short' });
+		} catch {
+			formatter = new Intl.DateTimeFormat('en-US', { timeZone: 'UTC', timeZoneName: 'short' });
+		}
+		TIME_ZONE_SHORT_FORMATTERS.set(key, formatter);
+	}
+	try {
+		for (let part of formatter.formatToParts(new Date(Number(_ms) || 0))) {
+			if (part.type === 'timeZoneName') return part.value;
+		}
+	} catch {
+		// Invalid timezone — leave empty.
+	}
+	return '';
+}
+
 /** Decomposes a timestamp into date/time placeholders (local tz + utc variants). */
-function _DatePlaceholders(_value, _timeZone) {
+function _DatePlaceholders(_value, _timeZone, _lid) {
 	let ms = Number(_value) || 0;
-	let local = _WallClockParts(ms, _timeZone);
+	let tz = _timeZone || 'UTC';
+	let local = _WallClockParts(ms, tz);
 	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',
+		weekofyear: _IsoWeekOfYear(local.year, local.month, local.day),
+		dayofyear: _DayOfYear(local.year, local.month, local.day),
+		timezone: tz,
+		timezoneoffset: _TimeZoneOffsetJsMinutes(ms, tz),
+		timezoneshort: _TimeZoneShort(ms, tz, _lid),
+		timezoneplace: tz,
 		utcday: utcDate.getUTCDate(), utcmonth: utcDate.getUTCMonth(), utcyear: utcDate.getUTCFullYear(),
 		utchour: utcDate.getUTCHours(), utcminute: utcDate.getUTCMinutes(), utcsecond: utcDate.getUTCSeconds(),
 		utcweekday: utcDate.getUTCDay(), utcmillisecond: utcDate.getUTCMilliseconds(),
+		utcweekofyear: _IsoWeekOfYear(utcDate.getUTCFullYear(), utcDate.getUTCMonth(), utcDate.getUTCDate()),
+		utcdayofyear: _DayOfYear(utcDate.getUTCFullYear(), utcDate.getUTCMonth(), utcDate.getUTCDate()),
 	};
 }
 
@@ -432,7 +493,7 @@ 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 });
+	if (def.hasDateTags) Object.assign(placeholders, _DatePlaceholders(_value, _ctx.timeZone, _ctx.lid), { x: Number(_value) || 0 });
 	return Trans(def.xml, placeholders, _ctx);
 }
 

package/src/i18x-hyphen.mjs

@@ -0,0 +1,166 @@
+// ===========================================
+// i18x-hyphen.mjs — TeX-style hyphenation (µLib / i18xe-compatible)
+// © 2026 Meinolf Amekudzi
+// ===========================================
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const HYPHEN_CHAR = '\xAD'; // U+00AD soft hyphen
+const hyphenData = {};
+const hyphenCache = {};
+
+/** Directory holding hyphen rule files: env override or `<cwd>/i18x/prod`. */
+function _HyphenDir() {
+	return process.env.MICROGULP_I18X_HYPHEN_DIR || join(process.cwd(), 'i18x', 'prod');
+}
+
+/**
+ * Loads hyphen rules for a localization id from `<dir>/<lid>.hyphen.json`.
+ * Missing or broken files yield a no-op catalog (`{ exist: false }`).
+ * @param {string} _lid
+ * @returns {object}
+ */
+export function LoadHyphenData(_lid) {
+	if (hyphenData[_lid]) return hyphenData[_lid];
+	let data = { exist: false };
+	try {
+		let filePath = join(_HyphenDir(), _lid + '.hyphen.json');
+		if (existsSync(filePath)) data = JSON.parse(readFileSync(filePath, 'utf8'));
+	} catch {
+		// Malformed hyphen data must not break the build — fall back to no-op.
+	}
+	if (!data || typeof data !== 'object') data = { exist: false };
+	hyphenData[_lid] = data;
+	hyphenCache[_lid] = {};
+	return data;
+}
+
+/**
+ * Hyphenates a single word; returns the original when no rules exist.
+ * @param {string} _word
+ * @param {string} _lid
+ * @returns {string}
+ */
+export function WordHyphenation(_word, _lid) {
+	let word = String(_word);
+	let data = LoadHyphenData(_lid);
+	if (!data.exist) return word;
+	if (!hyphenCache[_lid]) hyphenCache[_lid] = {};
+	if (hyphenCache[_lid][word]) return hyphenCache[_lid][word];
+
+	let lower = word.toLowerCase();
+	let ret = word;
+
+	if (!data.exceptions?.[lower]) {
+		let sylbs = data.sylbs;
+		let minSylbs = data.minSylbs;
+		let maxSylbs = data.maxSylbs;
+		let l = word.length + 1;
+		let myword = '.' + lower;
+		let vals = new Array(l + 1).fill(0);
+		for (let i = 0; i < l; i++) {
+			let sylb = '';
+			for (let j = 0; (i + j) < l; j++) {
+				sylb += myword.charAt(i + j);
+				if (j >= minSylbs && j <= maxSylbs) {
+					if (Object.prototype.hasOwnProperty.call(sylbs, sylb)) {
+						let sylbVals = sylbs[sylb];
+						let sl = sylb.length;
+						for (let k = -1; k <= sl; k++) vals[i + k] = Math.max(sylbVals[k + 1], vals[i + k]);
+					}
+				} else if (j > maxSylbs) break;
+			}
+		}
+		ret = '';
+		let k = l - 3;
+		let m = 2;
+		l--;
+		for (let i = 0; i < l; i++) {
+			if ((vals[i] % 2) === 1 && i > m && i < k) ret += HYPHEN_CHAR;
+			ret += word.charAt(i);
+		}
+	} else {
+		let w = data.exceptions[lower];
+		let j = 0;
+		for (let i = 0; i < w.length; i++) {
+			if (w.charAt(i) === HYPHEN_CHAR) {
+				ret += word.charAt(j++);
+			} else {
+				ret += w.charAt(i);
+			}
+		}
+	}
+
+	hyphenCache[_lid][word] = ret;
+	return ret;
+}
+
+/**
+ * Hyphenates every word in a text; preserves HTML/XML tags.
+ * @param {string} _text
+ * @param {string} _lid
+ * @returns {string}
+ */
+export function Hyphenation(_text, _lid) {
+	let txts = String(_text);
+	let ret = [];
+
+	if (txts.indexOf('<') >= 0 && txts.indexOf('>') >= 0) {
+		let tags = {};
+		let matches = txts.match(/(<[^>]+>)/g);
+		if (matches != null) {
+			for (let i = 0; i < matches.length; i++) {
+				tags[matches[i]] = '\x7F' + i + '\x7F';
+				txts = txts.replace(matches[i], tags[matches[i]]);
+			}
+		}
+		let words = txts.split(' ');
+		for (let i = 0; i < words.length; i++) {
+			let t = words[i].trim();
+			ret.push(t ? WordHyphenation(t, _lid) : t);
+		}
+		txts = ret.join(' ');
+		if (matches != null) {
+			for (let i = 0; i < matches.length; i++) txts = txts.replace(tags[matches[i]], matches[i]);
+		}
+		return txts;
+	}
+
+	let words = txts.split(' ');
+	for (let i = 0; i < words.length; i++) {
+		let t = words[i].trim();
+		ret.push(t ? WordHyphenation(t, _lid) : t);
+	}
+	return ret.join(' ');
+}
+
+/** @param {string} _target @param {string} _name @param {Function} _value */
+function _DefinePrototype(_target, _name, _value) {
+	if (typeof _target[_name] !== 'function') {
+		Object.defineProperty(_target, _name, { value: _value, writable: true, configurable: true });
+	}
+}
+
+/**
+ * Installs µLib- and i18xe-compatible String hyphenation prototypes.
+ * @param {function(): string} [_resolveLid] defaults to empty string when omitted
+ */
+export function InstallHyphenPrototypes(_resolveLid) {
+	function _ResolveLid(_lid) {
+		if (_lid) return _lid;
+		try {
+			return _resolveLid?.() ?? '';
+		} catch {
+			return '';
+		}
+	}
+	let wordFn = function (_lid = '') { return WordHyphenation(String(this), _ResolveLid(_lid)); };
+	let textFn = function (_lid = '') { return Hyphenation(String(this), _ResolveLid(_lid)); };
+	_DefinePrototype(String.prototype, 'WordHyphenation', wordFn);
+	_DefinePrototype(String.prototype, 'Hyphenation', textFn);
+	_DefinePrototype(String.prototype, 'wordHyphenation', wordFn);
+	_DefinePrototype(String.prototype, 'hyphenation', textFn);
+}
+
+export default { HYPHEN_CHAR, LoadHyphenData, WordHyphenation, Hyphenation, InstallHyphenPrototypes };

package/src/i18x.mjs

@@ -32,6 +32,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';
+import { InstallHyphenPrototypes as _InstallHyphenPrototypes } from './i18x-hyphen.mjs';
 
 const DEFAULT_LID = 'en-US';
 
@@ -92,6 +93,22 @@ export function DateInTimeZone(_date, _timeZone) {
 	}
 }
 
+/**
+ * Offset in minutes (UTC minus wall-clock, same sign as Date.getTimezoneOffset).
+ * @param {Date|number} _date
+ * @param {string} [_timeZone]
+ * @returns {number}
+ */
+export function TimeZoneOffset(_date, _timeZone) {
+	let date = _date instanceof Date ? _date : new Date(Number(_date) || 0);
+	let shifted = DateInTimeZone(date, _timeZone);
+	let wallAsUTC = Date.UTC(
+		shifted.getFullYear(), shifted.getMonth(), shifted.getDate(),
+		shifted.getHours(), shifted.getMinutes(), shifted.getSeconds(), shifted.getMilliseconds(),
+	);
+	return Math.round((date.getTime() - wallAsUTC) / 60000);
+}
+
 /** Normalizes casing: language lower, 2-letter region upper, 4-letter script Title. */
 function _NormalizeLid(_lid) {
 	if (!_lid) return '';
@@ -229,9 +246,9 @@ function _FormatRegistry(_lid) {
 }
 
 /** Assembles the engine render context (language, timezone, format registry). */
-function _RenderContext(_lid) {
+function _RenderContext(_lid, _timeZone) {
 	let lid = _lid ?? GetLid();
-	return { lid, timeZone: GetTimeZone(), formats: _FormatRegistry(lid) };
+	return { lid, timeZone: _timeZone ?? GetTimeZone(), formats: _FormatRegistry(lid) };
 }
 
 /**
@@ -239,13 +256,15 @@ function _RenderContext(_lid) {
  * 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.
+ * Date/time formats interpret the value as milliseconds since the Unix epoch.
  * @param {number|string} _value
  * @param {string} _formatName e.g. 'int', 'floatFix2', 'byteSize', 'stdDateTime'
  * @param {string} [_lid]
+ * @param {string} [_timeZone] IANA timezone id (defaults to GetTimeZone())
  * @returns {string}
  */
-export function FormatValue(_value, _formatName, _lid) {
-	let context = _RenderContext(_lid);
+export function FormatValue(_value, _formatName, _lid, _timeZone) {
+	let context = _RenderContext(_lid, _timeZone);
 	if (!Object.prototype.hasOwnProperty.call(context.formats, _formatName)) return String(_value);
 	return EngineFormatValue(_value, _formatName, context);
 }
@@ -256,9 +275,10 @@ export function FormatValue(_value, _formatName, _lid) {
  * `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
+ * @param {string} [_timeZone] IANA timezone id (defaults to GetTimeZone())
  * @returns {string}
  */
-export function Translate(_text, _values) {
+export function Translate(_text, _values, _timeZone) {
 	if (_text == null) return '';
 	let source = String(_text);
 	let lid = GetLid();
@@ -266,7 +286,7 @@ export function Translate(_text, _values) {
 	let translated = (dictionary && Object.prototype.hasOwnProperty.call(dictionary, source)) ? dictionary[source] : source;
 	// 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));
+	return EngineTrans(translated, _values ?? {}, _RenderContext(lid, _timeZone));
 }
 
 /**
@@ -308,7 +328,7 @@ export function LogError(_text, _values) {
 export function InstallStringExtensions() {
 	if (typeof String.prototype.I18xTrans !== 'function') {
 		Object.defineProperty(String.prototype, 'I18xTrans', {
-			value: function (_values) { return Translate(String(this), _values); },
+			value: function (_values, _timeZone) { return Translate(String(this), _values, _timeZone); },
 			writable: true, configurable: true,
 		});
 	}
@@ -330,11 +350,73 @@ export function InstallStringExtensions() {
 			writable: true, configurable: true,
 		});
 	}
+	InstallFormatPrototypes();
+	InstallHyphenPrototypes();
+}
+
+/**
+ * Installs String hyphenation prototypes (µLib + i18xe aliases). Called from
+ * InstallStringExtensions (auto-run on import); also exported for explicit control.
+ */
+export function InstallHyphenPrototypes() {
+	_InstallHyphenPrototypes(GetLid);
+}
+
+// .NET ticks are 100-nanosecond intervals since 0001-01-01; this offset is the
+// tick count at the Unix epoch (1970-01-01), so ms = (ticks - offset) / 10000.
+const TICKS_EPOCH_OFFSET = 621355968000000000;
+const TICKS_PER_MILLISECOND = 10000;
+
+/** @param {string} _name @param {Function} _value install a prototype method only if absent (µLib wins) */
+function _DefinePrototype(_target, _name, _value) {
+	if (typeof _target[_name] !== 'function') {
+		Object.defineProperty(_target, _name, { value: _value, writable: true, configurable: true });
+	}
+}
+
+/**
+ * µLib-compatible Number/Date/String `Format` prototypes for gulpfiles that
+ * prefer `(1536).Format('byteSize')` or `new Date().Format('stdDateTime')`
+ * over the FormatValue() helper. Date/time formats interpret their value as
+ * milliseconds since the Unix epoch (µGulp convention), except FormatTicks
+ * which takes .NET ticks. Never overwrites an implementation already provided
+ * by µLib (µLib wins when both are loaded). Called from InstallStringExtensions
+ * (auto-run on import); also exported for explicit control.
+ */
+export function InstallFormatPrototypes() {
+	// Number.prototype.Format — number formats use the value directly, date
+	// formats interpret it as milliseconds since the Unix epoch.
+	_DefinePrototype(Number.prototype, 'Format', function (_format, _lid, _timeZone) {
+		return FormatValue(this.valueOf(), _format, _lid, _timeZone);
+	});
+	// Number.prototype.FormatTimestamp — an explicit Unix millisecond timestamp.
+	_DefinePrototype(Number.prototype, 'FormatTimestamp', function (_format, _lid, _timeZone) {
+		return FormatValue(this.valueOf(), _format, _lid, _timeZone);
+	});
+	// Number.prototype.FormatTicks — a .NET tick count, converted to ms first.
+	_DefinePrototype(Number.prototype, 'FormatTicks', function (_format, _lid, _timeZone) {
+		let ms = (this.valueOf() - TICKS_EPOCH_OFFSET) / TICKS_PER_MILLISECOND;
+		return FormatValue(ms, _format, _lid, _timeZone);
+	});
+	// i18xe-sync lowercase aliases.
+	_DefinePrototype(Number.prototype, 'format', Number.prototype.Format);
+	_DefinePrototype(Number.prototype, 'formatTimestamp', Number.prototype.FormatTimestamp);
+	_DefinePrototype(Number.prototype, 'formatTicks', Number.prototype.FormatTicks);
+	// Date.prototype.Format — formats via the date's millisecond timestamp.
+	_DefinePrototype(Date.prototype, 'Format', function (_format, _lid, _timeZone) {
+		return FormatValue(this.getTime(), _format, _lid, _timeZone);
+	});
+	_DefinePrototype(Date.prototype, 'format', Date.prototype.Format);
+	// String.prototype.Format — µLib parity: a string has no numeric format.
+	_DefinePrototype(String.prototype, 'Format', function () {
+		return this.valueOf();
+	});
 }
 
 InstallStringExtensions();
 
 export default {
-	GetLid, SetLid, GetTimeZone, DateInTimeZone,
-	Translate, FormatValue, Log, Warn, LogError, InstallStringExtensions,
+	GetLid, SetLid, GetTimeZone, DateInTimeZone, TimeZoneOffset,
+	Translate, FormatValue, Log, Warn, LogError,
+	InstallStringExtensions, InstallFormatPrototypes, InstallHyphenPrototypes,
 };

package/src/index.mjs

@@ -30,7 +30,8 @@
 
 // Localized console output (i18x). Re-exported so tasks import everything
 // from one place: `import { Log, Warn, ReportProgress } from 'gulp-mu-gulp-api'`.
-export { Log, Warn, LogError, Translate, FormatValue, GetLid, SetLid, GetTimeZone, DateInTimeZone, InstallStringExtensions } from './i18x.mjs';
+export { Log, Warn, LogError, Translate, FormatValue, GetLid, SetLid, GetTimeZone, DateInTimeZone, TimeZoneOffset, InstallStringExtensions, InstallFormatPrototypes, InstallHyphenPrototypes } from './i18x.mjs';
+export { WordHyphenation, Hyphenation, LoadHyphenData } from './i18x-hyphen.mjs';
 import * as I18x from './i18x.mjs';
 
 let uiRequestCounter = 0;
@@ -207,6 +208,77 @@ export function LogBuildDebugReport(_report, _options = {}) {
 	});
 }
 
+/**
+ * Sends a highlighted callout box (info/success/warning/error) to the dashboard
+ * log pane. The payload is JSON: `{ variant, title?, message }`.
+ * CLI fallback: a bracketed line on stdout.
+ *
+ * @param {object} _spec `{ variant?: 'info'|'success'|'warning'|'error', title?, message }`
+ */
+export function LogCallout(_spec) {
+	let payload = _NormalizeCalloutSpec(_spec);
+	if (_SendStructuredLog('callout', payload)) return;
+	let head = payload.variant.toUpperCase() + (payload.title ? ': ' + payload.title : '');
+	console.log('[' + head + '] ' + payload.message);
+}
+
+/**
+ * Sends a key/value list (metrics, build summary, environment) to the dashboard
+ * log pane. The payload is JSON: `{ title?, items: {key, value}[] }`.
+ * CLI fallback: aligned `key: value` lines on stdout.
+ *
+ * @param {object} _spec `{ title?, items: Array<{key, value}> | Record<string, any> }`
+ */
+export function LogKeyValue(_spec) {
+	let payload = _NormalizeKeyValueSpec(_spec);
+	if (_SendStructuredLog('key-value', payload)) return;
+	if (payload.title) console.log(payload.title);
+	let width = payload.items.reduce((_max, _item) => Math.max(_max, _item.key.length), 0);
+	for (let item of payload.items) console.log('  ' + item.key.padEnd(width) + '  ' + item.value);
+}
+
+/**
+ * Sends a row of status badges/chips to the dashboard log pane. The payload is
+ * JSON: `{ title?, items: {label, variant?}[] }`.
+ * CLI fallback: bracketed labels on one stdout line.
+ *
+ * @param {object} _spec `{ title?, items: Array<string|{label, variant?}> }`
+ */
+export function LogBadges(_spec) {
+	let payload = _NormalizeBadgesSpec(_spec);
+	if (_SendStructuredLog('badges', payload)) return;
+	let chips = payload.items.map((_item) => '[' + _item.label + ']').join(' ');
+	console.log((payload.title ? payload.title + ' ' : '') + chips);
+}
+
+/**
+ * Sends a code block (monospace, preserved whitespace) to the dashboard log
+ * pane. The payload is JSON: `{ title?, language?, code }`.
+ * CLI fallback: the code printed verbatim on stdout.
+ *
+ * @param {object} _spec `{ title?, language?, code }`
+ */
+export function LogCode(_spec) {
+	let payload = _NormalizeCodeSpec(_spec);
+	if (_SendStructuredLog('code', payload)) return;
+	if (payload.title) console.log(payload.title + (payload.language ? ' (' + payload.language + ')' : ''));
+	console.log(payload.code);
+}
+
+/**
+ * Sends a bar chart to the dashboard log pane, rendered as inline SVG (no
+ * scripts — Content-Security-Policy safe). The payload is JSON:
+ * `{ title?, type?: 'bar', series: {label, value, color?}[], max?, unit? }`.
+ * CLI fallback: an ASCII bar chart on stdout.
+ *
+ * @param {object} _spec `{ title?, type?, series: Array<{label, value, color?}>, max?, unit? }`
+ */
+export function LogChart(_spec) {
+	let payload = _NormalizeChartSpec(_spec);
+	if (_SendStructuredLog('chart', payload)) return;
+	for (let line of _AsciiChart(payload)) console.log(line);
+}
+
 // -------------------------------------------------
 // sound & speech
 // -------------------------------------------------
@@ -553,6 +625,98 @@ function _AsciiGallery(_payload) {
 	return lines.join('\n');
 }
 
+const CALLOUT_VARIANTS = new Set(['info', 'success', 'warning', 'error']);
+
+function _NormalizeCalloutSpec(_spec) {
+	let variant = String(_spec?.variant ?? 'info').toLowerCase();
+	if (!CALLOUT_VARIANTS.has(variant)) variant = 'info';
+	return {
+		variant,
+		title: _spec?.title != null ? String(_spec.title) : '',
+		message: String(_spec?.message ?? _spec?.text ?? ''),
+	};
+}
+
+function _NormalizeKeyValueSpec(_spec) {
+	let rawItems = _spec?.items ?? _spec ?? [];
+	let items = [];
+	if (Array.isArray(rawItems)) {
+		for (let item of rawItems) {
+			if (item == null) continue;
+			if (typeof item === 'object' && !Array.isArray(item)) {
+				items.push({ key: String(item.key ?? ''), value: String(item.value ?? '') });
+			} else if (Array.isArray(item)) {
+				items.push({ key: String(item[0] ?? ''), value: String(item[1] ?? '') });
+			}
+		}
+	} else if (rawItems && typeof rawItems === 'object') {
+		for (let [key, value] of Object.entries(rawItems)) {
+			if (key === 'title') continue;
+			items.push({ key: String(key), value: String(value) });
+		}
+	}
+	return { title: _spec?.title != null ? String(_spec.title) : '', items };
+}
+
+const BADGE_VARIANTS = new Set(['neutral', 'info', 'success', 'warning', 'error']);
+
+function _NormalizeBadgesSpec(_spec) {
+	let items = (_spec?.items ?? []).map((_item) => {
+		if (_item == null) return null;
+		if (typeof _item === 'object') {
+			let variant = String(_item.variant ?? 'neutral').toLowerCase();
+			return { label: String(_item.label ?? _item.value ?? ''), variant: BADGE_VARIANTS.has(variant) ? variant : 'neutral' };
+		}
+		return { label: String(_item), variant: 'neutral' };
+	}).filter((_item) => _item && _item.label);
+	return { title: _spec?.title != null ? String(_spec.title) : '', items };
+}
+
+function _NormalizeCodeSpec(_spec) {
+	return {
+		title: _spec?.title != null ? String(_spec.title) : '',
+		language: _spec?.language != null ? String(_spec.language) : '',
+		code: String(_spec?.code ?? _spec?.text ?? ''),
+	};
+}
+
+function _NormalizeChartSpec(_spec) {
+	let series = (_spec?.series ?? _spec?.data ?? []).map((_entry) => {
+		if (_entry == null) return null;
+		if (typeof _entry === 'object' && !Array.isArray(_entry)) {
+			return {
+				label: String(_entry.label ?? ''),
+				value: Number(_entry.value) || 0,
+				color: _entry.color != null ? String(_entry.color) : '',
+			};
+		}
+		if (Array.isArray(_entry)) return { label: String(_entry[0] ?? ''), value: Number(_entry[1]) || 0, color: '' };
+		return { label: '', value: Number(_entry) || 0, color: '' };
+	}).filter(Boolean);
+	let explicitMax = Number(_spec?.max);
+	let dataMax = series.reduce((_max, _entry) => Math.max(_max, _entry.value), 0);
+	return {
+		title: _spec?.title != null ? String(_spec.title) : '',
+		type: 'bar',
+		unit: _spec?.unit != null ? String(_spec.unit) : '',
+		max: Number.isFinite(explicitMax) && explicitMax > 0 ? explicitMax : (dataMax || 1),
+		series,
+	};
+}
+
+function _AsciiChart(_payload) {
+	let lines = [];
+	if (_payload.title) lines.push(_payload.title);
+	let labelWidth = _payload.series.reduce((_max, _entry) => Math.max(_max, _entry.label.length), 0);
+	const BAR_WIDTH = 24;
+	for (let entry of _payload.series) {
+		let filled = _payload.max > 0 ? Math.round((entry.value / _payload.max) * BAR_WIDTH) : 0;
+		let bar = '\u2588'.repeat(filled) + '\u00b7'.repeat(Math.max(0, BAR_WIDTH - filled));
+		lines.push('  ' + entry.label.padEnd(labelWidth) + '  ' + bar + '  ' + entry.value + (_payload.unit ? ' ' + _payload.unit : ''));
+	}
+	return lines;
+}
+
 export default {
 	IsMicroGulp,
 	IsµGulp,
@@ -576,10 +740,18 @@ export default {
 	SetLid: I18x.SetLid,
 	GetTimeZone: I18x.GetTimeZone,
 	DateInTimeZone: I18x.DateInTimeZone,
+	TimeZoneOffset: I18x.TimeZoneOffset,
 	InstallStringExtensions: I18x.InstallStringExtensions,
+	InstallFormatPrototypes: I18x.InstallFormatPrototypes,
+	InstallHyphenPrototypes: I18x.InstallHyphenPrototypes,
 	LogTable,
 	LogTree,
 	LogGallery,
 	LogAssetPreviews,
 	LogBuildDebugReport,
+	LogCallout,
+	LogKeyValue,
+	LogBadges,
+	LogCode,
+	LogChart,
 };