gulp-mu-gulp-api 0.3.9 → 0.3.11

package/src/index.mjs

@@ -1,770 +1,843 @@
-// ===========================================
-// gulp-mu-gulp-api — µGulp task API
-// © 2026 Meinolf Amekudzi
-// (published under MIT license)
-// ===========================================
-
-/**
- * Public API for gulp tasks running under the µGulp orchestrator.
- *
- * Under µGulp every task runs inside a forked worker process with an IPC
- * channel to the engine; this module talks to that channel directly, so it
- * has zero coupling to µGulp internals and works from any npm package in
- * the pipeline. Without µGulp (plain "gulp" CLI run) every function
- * degrades gracefully: progress renders on the terminal, inputs fall back
- * to readline prompts on a TTY or to the declared defaults otherwise.
- *
- * @example
- * import { ReportProgress, RequestTextInput, RequestColorInput } from 'gulp-mu-gulp-api';
- *
- * export async function BUILD_THEME() {
- *     let accent = await RequestColorInput({ label: 'Accent color', default: '#00e5ff' });
- *     for (let step = 0; step < 10; step++) {
- *         // ... work ...
- *         ReportProgress((step + 1) / 10, 'compiling theme');
- *     }
- * }
- *
- * @module gulp-mu-gulp-api
- */
-
-// 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, TimeZoneOffset, InstallStringExtensions, InstallFormatPrototypes, InstallHyphenPrototypes } from './i18x.mjs';
-export { WordHyphenation, Hyphenation, LoadHyphenData } from './i18x-hyphen.mjs';
-import * as I18x from './i18x.mjs';
-
-let uiRequestCounter = 0;
-let ipcListenerAttached = false;
-let lastLoggedPercent = -1;
-const pendingUiRequests = new Map();
-
-/**
- * @returns {boolean} true when the task runs inside a µGulp worker with an
- * attached dashboard (progress and inputs are rendered in the webview)
- */
-export function IsMicroGulp() {
-	// The worker pool sets MICROGULP=1 for every forked task process. Relying
-	// only on process.send was too strict — some hosts still stream stdout
-	// correctly while structured IPC must be attempted separately.
-	return process.env.MICROGULP === '1';
-}
-
-/** Brand-aligned alias for {@link IsMicroGulp}. */
-export const IsµGulp = IsMicroGulp;
-
-/*
- * Task metadata (µDisplayName, µDescription, µTooltip, µGroup) is localized
- * the same way as any other i18x phrase: with the context tag written *into*
- * the source phrase and a String.prototype.i18xRegister() marker so the
- * i18xe-sync tooling extracts it and the dashboard can translate it later.
- *
- *   MAKE_BUILDS.µDisplayName =
- *       'Make Build V<version/><context="µDisplayName"/>'.i18xRegister();
- *
- * i18xRegister() returns the phrase unchanged (the i18x key), so the classic
- * gulp CLI keeps seeing a plain string while the dashboard translates it via
- * the merged project dictionary. The prototype is installed by
- * InstallStringExtensions() (auto-run on import of this module).
- */
-
-// -------------------------------------------------
-// progress
-// -------------------------------------------------
-
-/**
- * Reports task progress to the µGulp dashboard (determinate neon progress
- * bar in the task's sector). CLI fallback: an updating line on a TTY,
- * 10%-step log lines otherwise.
- *
- * @param {number} _value progress in the range 0..1
- * @param {string} [_label] short status label shown next to the bar
- */
-export function ReportProgress(_value, _label) {
-	let value = Math.max(0, Math.min(1, Number(_value) || 0));
-	if (IsMicroGulp()) {
-		process.send({ type: 'progress', value, label: _label });
-		return;
-	}
-	let percent = Math.round(value * 100);
-	if (process.stdout.isTTY) {
-		process.stdout.write('\r' + (_label ?? 'progress') + ' ' + percent + '%' + (value >= 1 ? '\n' : ''));
-	} else if (percent >= 100 || percent - lastLoggedPercent >= 10) {
-		lastLoggedPercent = percent >= 100 ? -1 : percent;
-		console.log((_label ?? 'progress') + ' ' + percent + '%');
-	}
-}
-
-/**
- * Convenience wrapper that carries a fixed label.
- *
- * @param {string} [_label]
- * @returns {{Update: function(number, string=): void, Done: function(): void}}
- */
-export function CreateProgress(_label) {
-	return {
-		Update(_value, _stepLabel) {
-			ReportProgress(_value, _stepLabel ?? _label);
-		},
-		Done() {
-			ReportProgress(1, _label);
-		},
-	};
-}
-
-function _SendStructuredLog(_format, _payload) {
-	if (!IsMicroGulp()) return false;
-	if (typeof process.send !== 'function') return false;
-	process.send({ type: 'structured-log', format: _format, payload: _payload });
-	return true;
-}
-
-/**
- * Sends a table to the dashboard log pane. The payload is JSON:
- * `{ columns: string[] | {id, label}[], rows: (string|number)[][] | object[], hyphenate?: boolean }`.
- * CLI fallback: a simple ASCII table on stdout.
- *
- * @param {object} _spec table descriptor
- */
-export function LogTable(_spec) {
-	let payload = _NormalizeTableSpec(_spec);
-	if (_SendStructuredLog('table', payload)) return;
-	console.log(_AsciiTable(payload));
-}
-
-/**
- * Sends a tree structure to the dashboard log pane. The payload is JSON:
- * `{ label?: string, children?: object[], roots?: object[] }` where each node
- * has `{ label, children? }`. CLI fallback: indented text lines.
- *
- * @param {object} _spec tree descriptor (single root or `{ roots: [...] }`)
- */
-export function LogTree(_spec) {
-	let payload = _NormalizeTreeSpec(_spec);
-	if (_SendStructuredLog('tree', payload)) return;
-	for (let line of _AsciiTreeLines(payload)) console.log(line);
-}
-
-/**
- * Sends an image gallery to the dashboard log pane. Each item needs a `src`
- * (data URI or https URL) and a `label`; optional `caption` and per-item `title`.
- * CLI fallback: lists labels and src lengths on stdout.
- *
- * @param {object} _spec `{ title?, columns?, items: { label, src, caption?, title? }[] }`
- */
-export function LogGallery(_spec) {
-	let payload = _NormalizeGallerySpec(_spec);
-	if (_SendStructuredLog('gallery', payload)) return;
-	console.log(_AsciiGallery(payload));
-}
-
-/**
- * Renders µCSS BuildSkin `report.debug.previews` as a thumbnail gallery.
- * Items without `thumbDataUri` are omitted (paths-only assets stay in the text log).
- *
- * @param {object[]} _previews preview entries from `report.debug.previews`
- * @param {object} [_options] `{ title?, columns? }`
- */
-export function LogAssetPreviews(_previews, _options = {}) {
-	let items = (_previews ?? [])
-		.filter((_entry) => _entry?.thumbDataUri)
-		.map((_entry) => ({
-			label: String(_entry.relPath ?? _entry.path ?? ''),
-			src: _entry.thumbDataUri,
-			caption: [
-				_entry.step,
-				_entry.skipped ? 'cached' : null,
-				_entry.width && _entry.height ? `${_entry.width}\u00d7${_entry.height}` : null,
-			].filter(Boolean).join(' \u00b7 '),
-		}));
-	if (!items.length) return;
-	LogGallery({
-		title: _options.title,
-		columns: _options.columns ?? 4,
-		items,
-	});
-}
-
-/**
- * Convenience wrapper for a full µCSS `BuildSkin` debug block: summary table
- * plus thumbnail gallery when `report.debug` is present.
- *
- * @param {object} _report BuildSkin return value
- * @param {object} [_options] `{ title?, columns?, table?: boolean }`
- */
-export function LogBuildDebugReport(_report, _options = {}) {
-	let debug = _report?.debug;
-	if (!debug) return;
-	if (_options.table !== false && debug.summary) {
-		LogTable({
-			columns: [{ id: 'metric', label: 'Metric' }, { id: 'value', label: 'Value' }],
-			rows: Object.entries(debug.summary).map(([metric, value]) => ({ metric, value: String(value) })),
-			hyphenate: false,
-		});
-	}
-	LogAssetPreviews(debug.previews, {
-		title: _options.title ?? 'Generated assets',
-		columns: _options.columns,
-	});
-}
-
-/**
- * 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
-// -------------------------------------------------
-
-/**
- * Plays an acoustic signal in the µGulp dashboard (WebAudio, respects the
- * dashboard audio settings: mute/volume). CLI fallback: terminal bell for
- * 'attention' and 'error' on a TTY, silent otherwise.
- *
- * @param {'success'|'error'|'attention'} [_signal]
- */
-export function PlaySignal(_signal = 'attention') {
-	if (IsMicroGulp()) {
-		process.send({ type: 'sound', signal: _signal });
-		return;
-	}
-	if (process.stdout.isTTY && (_signal === 'attention' || _signal === 'error')) {
-		process.stdout.write('\u0007');
-	}
-}
-
-/**
- * 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).
- * CLI fallback: the text is printed as a log line.
- *
- * @param {string} _text
- * @param {object} [_options] { rate?, pitch?, volume? } — per-call overrides (0..2 / 0..2 / 0..1)
- */
-export function Speak(_text, _options) {
-	let text = String(_text ?? '').trim();
-	if (!text) return;
-	if (IsMicroGulp()) {
-		process.send({ type: 'speech', text, options: _options ?? null });
-		return;
-	}
-	console.log('[speech] ' + text);
-}
-
-// -------------------------------------------------
-// interactive inputs
-// -------------------------------------------------
-
-/**
- * Requests a complete form from the µGulp dashboard.
- *
- * Field descriptor: { id, type, label, default?, options?, validate?,
- * min?, max?, step?, rows?, placeholder? }
- *
- * Supported types: 'text' | 'password' | 'number' | 'textarea' | 'color' |
- * 'font' | 'select' | 'radio' | 'checkbox' (multi-select, resolves to a
- * string array) | 'range' (slider with synced number box) | 'date' |
- * 'time' | 'datetime' | 'file'.
- *
- * Options (select/radio/checkbox) accept plain strings or objects
- * { value, label?, checked?, disabled? }.
- *
- * Validation rules: { required?, minLength?, pattern?, minSelected? } —
- * checks run asynchronously in the webview before submission.
- *
- * @param {object} _form { title, fields: [...] }
- * @returns {Promise<object>} map fieldId -> value
- */
-export async function RequestForm(_form) {
-	if (IsMicroGulp()) {
-		_EnsureIpcListener();
-		let requestId = 'api-req-' + process.pid + '-' + (++uiRequestCounter);
-		return new Promise((_resolve) => {
-			pendingUiRequests.set(requestId, _resolve);
-			process.send({ type: 'ui-request', requestId, form: _form });
-		});
-	}
-	return _FallbackForm(_form);
-}
-
-/**
- * Requests a single validated text value.
- * @param {object} _options { label, title?, default?, validate? }
- * @returns {Promise<string|null>}
- */
-export async function RequestTextInput(_options) {
-	return _SingleField({ ..._options, type: 'text' });
-}
-
-/**
- * Requests a color (native color picker in the dashboard).
- * @param {object} _options { label, title?, default? } — default as #rrggbb
- * @returns {Promise<string|null>}
- */
-export async function RequestColorInput(_options) {
-	return _SingleField({ ..._options, type: 'color' });
-}
-
-/**
- * Requests a font selection.
- * @param {object} _options { label, title?, default?, options? } — options: font family names
- * @returns {Promise<string|null>}
- */
-export async function RequestFontInput(_options) {
-	return _SingleField({ ..._options, type: 'font' });
-}
-
-/**
- * Requests a selection from a fixed option list.
- * @param {object} _options { label, title?, default?, options: string[] }
- * @returns {Promise<string|null>}
- */
-export async function RequestSelectInput(_options) {
-	return _SingleField({ ..._options, type: 'select' });
-}
-
-/**
- * Requests a multi-selection (checkbox group in the dashboard).
- * @param {object} _options { label, title?, options: Array<string|{value, label?, checked?, disabled?}>, validate? }
- * @returns {Promise<string[]>} selected values (empty array when nothing was picked)
- */
-export async function RequestMultiSelectInput(_options) {
-	let value = await _SingleField({ ..._options, type: 'checkbox' });
-	return Array.isArray(value) ? value : (value != null ? [value] : []);
-}
-
-// -------------------------------------------------
-// internal
-// -------------------------------------------------
-
-function _EnsureIpcListener() {
-	if (ipcListenerAttached) return;
-	ipcListenerAttached = true;
-	process.on('message', (_message) => {
-		if (_message && _message.type === 'ui-response' && pendingUiRequests.has(_message.requestId)) {
-			let resolver = pendingUiRequests.get(_message.requestId);
-			pendingUiRequests.delete(_message.requestId);
-			resolver(_message.payload);
-		}
-	});
-}
-
-async function _SingleField(_options) {
-	let values = await RequestForm({
-		title: _options.title ?? _options.label,
-		fields: [{
-			id: 'value',
-			type: _options.type,
-			label: _options.label,
-			default: _options.default,
-			options: _options.options,
-			validate: _options.validate,
-		}],
-	});
-	return values.value ?? null;
-}
-
-async function _FallbackForm(_form) {
-	let values = {};
-	for (let field of _form.fields ?? []) {
-		values[field.id] = await _FallbackField(field);
-	}
-	return values;
-}
-
-function _NormalizeOptions(_options) {
-	let result = [];
-	for (let option of _options ?? []) {
-		if (option == null) continue;
-		if (typeof option === 'object') {
-			if (option.separator) continue;
-			let value = option.value ?? option.label ?? option.name ?? '';
-			result.push({
-				value: String(value),
-				label: String(option.label ?? option.name ?? value),
-				checked: !!option.checked,
-			});
-		} else {
-			result.push({ value: String(option), label: String(option), checked: false });
-		}
-	}
-	return result;
-}
-
-function _FallbackDefault(_field) {
-	if (_field.type === 'checkbox') {
-		return _NormalizeOptions(_field.options).filter((_option) => _option.checked).map((_option) => _option.value);
-	}
-	return _field.default ?? null;
-}
-
-async function _FallbackField(_field) {
-	if (!process.stdin.isTTY || !process.stdout.isTTY) {
-		return _FallbackDefault(_field);
-	}
-	const readline = await import('node:readline/promises');
-	let prompt = readline.createInterface({ input: process.stdin, output: process.stdout });
-	try {
-		let label = _field.label ?? _field.id;
-		let options = _NormalizeOptions(_field.options);
-		let hasOptions = options.length > 0;
-		if (_field.type === 'checkbox' && hasOptions) {
-			options.forEach((_option, _index) => console.log('  [' + (_index + 1) + '] ' + _option.label + (_option.checked ? ' *' : '')));
-			let answer = await prompt.question(label + ' (comma-separated numbers, Enter = defaults marked *): ');
-			let picked = answer.split(',')
-				.map((_part) => parseInt(_part.trim(), 10))
-				.filter((_index) => _index >= 1 && _index <= options.length)
-				.map((_index) => options[_index - 1].value);
-			return picked.length > 0 ? picked : _FallbackDefault(_field);
-		}
-		if ((_field.type === 'select' || _field.type === 'font' || _field.type === 'radio') && hasOptions) {
-			options.forEach((_option, _index) => console.log('  [' + (_index + 1) + '] ' + _option.label));
-			let answer = await prompt.question(label + ' (1-' + options.length + (_field.default ? ', default "' + _field.default + '"' : '') + '): ');
-			let index = parseInt(answer, 10);
-			if (index >= 1 && index <= options.length) return options[index - 1].value;
-			return _field.default ?? null;
-		}
-		let hint = _field.type === 'range' || _field.type === 'number'
-			? ' (' + (_field.min ?? 0) + '-' + (_field.max ?? 100) + (_field.default != null ? ', default ' + _field.default : '') + ')'
-			: (_field.default ? ' [' + _field.default + ']' : '');
-		let answer = await prompt.question(label + hint + ': ');
-		return answer || (_field.default ?? null);
-	} finally {
-		prompt.close();
-	}
-}
-
-function _NormalizeColumn(_column, _index) {
-	if (typeof _column === 'string') return { id: 'c' + _index, label: _column };
-	return { id: String(_column.id ?? 'c' + _index), label: String(_column.label ?? _column.id ?? 'c' + _index) };
-}
-
-function _NormalizeTableSpec(_spec) {
-	let columns = (_spec?.columns ?? []).map(_NormalizeColumn);
-	let rows = _spec?.rows ?? [];
-	let normalizedRows = rows.map((_row) => {
-		if (Array.isArray(_row)) {
-			let obj = {};
-			for (let c = 0; c < columns.length; c++) obj[columns[c].id] = _row[c] ?? '';
-			return obj;
-		}
-		return _row;
-	});
-	return { columns, rows: normalizedRows, hyphenate: _spec?.hyphenate !== false };
-}
-
-function _NormalizeTreeSpec(_spec) {
-	if (_spec?.roots) return { roots: _spec.roots };
-	if (_spec?.label != null || _spec?.children) return { roots: [_spec] };
-	return { roots: [] };
-}
-
-function _AsciiTable(_payload) {
-	let headers = _payload.columns.map((_c) => _c.label);
-	let widths = headers.map((_h) => _h.length);
-	for (let row of _payload.rows) {
-		for (let c = 0; c < _payload.columns.length; c++) {
-			let cell = String(row[_payload.columns[c].id] ?? '');
-			widths[c] = Math.max(widths[c], cell.length);
-		}
-	}
-	let sep = widths.map((_w) => '-'.repeat(_w)).join('-+-');
-	let lines = [headers.map((_h, _i) => _h.padEnd(widths[_i])).join(' | ')];
-	lines.push(sep);
-	for (let row of _payload.rows) {
-		lines.push(_payload.columns.map((_col, _i) => String(row[_col.id] ?? '').padEnd(widths[_i])).join(' | '));
-	}
-	return lines.join('\n');
-}
-
-function _AsciiTreeLines(_payload, _indent = '', _roots = null) {
-	let roots = _roots ?? _payload.roots ?? [];
-	let lines = [];
-	for (let i = 0; i < roots.length; i++) {
-		let node = roots[i];
-		let branch = i < roots.length - 1 ? '├─ ' : '└─ ';
-		lines.push(_indent + branch + String(node.label ?? ''));
-		let childIndent = _indent + (i < roots.length - 1 ? '│  ' : '   ');
-		if (node.children?.length) lines.push(..._AsciiTreeLines(_payload, childIndent, node.children));
-	}
-	return lines;
-}
-
-function _NormalizeGallerySpec(_spec) {
-	let columns = Math.max(1, Math.min(8, Number(_spec?.columns) || 4));
-	let items = (_spec?.items ?? []).map((_item) => ({
-		label: String(_item?.label ?? ''),
-		src: String(_item?.src ?? ''),
-		caption: _item?.caption != null ? String(_item.caption) : '',
-		title: _item?.title != null ? String(_item.title) : '',
-	})).filter((_item) => _item.src);
-	return {
-		title: _spec?.title != null ? String(_spec.title) : '',
-		columns,
-		items,
-	};
-}
-
-function _AsciiGallery(_payload) {
-	let lines = [];
-	if (_payload.title) lines.push(_payload.title);
-	for (let item of _payload.items) {
-		let meta = item.caption ? ` (${item.caption})` : '';
-		let srcHint = item.src.startsWith('data:') ? `[data URI, ${item.src.length} chars]` : item.src;
-		lines.push(`  ${item.label}${meta}: ${srcHint}`);
-	}
-	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;
-}
-
-/**
- * Asks µGulp to re-evaluate dynamic task metadata (µEnabled predicates,
- * disabled tooltips) and refresh the dashboard task list. Call after
- * changing module-level state that drives enable/disable rules.
- * No-op outside a µGulp worker.
- */
-export function NotifyTasksChanged() {
-	if (typeof process.send === 'function') {
-		process.send({ type: 'refresh-tasks' });
-	}
-}
-
-export default {
-	IsMicroGulp,
-	IsµGulp,
-	NotifyTasksChanged,
-	ReportProgress,
-	CreateProgress,
-	PlaySignal,
-	PlaySound,
-	StopSound,
-	Speak,
-	RequestForm,
-	RequestTextInput,
-	RequestColorInput,
-	RequestFontInput,
-	RequestSelectInput,
-	RequestMultiSelectInput,
-	Log: I18x.Log,
-	Warn: I18x.Warn,
-	LogError: I18x.LogError,
-	Translate: I18x.Translate,
-	GetLid: I18x.GetLid,
-	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,
-};
+// ===========================================
+// gulp-mu-gulp-api — µGulp task API
+// © 2026 Meinolf Amekudzi
+// (published under MIT license)
+// ===========================================
+
+/**
+ * Public API for gulp tasks running under the µGulp orchestrator.
+ *
+ * Under µGulp every task runs inside a forked worker process with an IPC
+ * channel to the engine; this module talks to that channel directly, so it
+ * has zero coupling to µGulp internals and works from any npm package in
+ * the pipeline. Without µGulp (plain "gulp" CLI run) every function
+ * degrades gracefully: progress renders on the terminal, inputs fall back
+ * to readline prompts on a TTY or to the declared defaults otherwise.
+ *
+ * @example
+ * import { ReportProgress, RequestTextInput, RequestColorInput } from 'gulp-mu-gulp-api';
+ *
+ * export async function BUILD_THEME() {
+ *     let accent = await RequestColorInput({ label: 'Accent color', default: '#00e5ff' });
+ *     for (let step = 0; step < 10; step++) {
+ *         // ... work ...
+ *         ReportProgress((step + 1) / 10, 'compiling theme');
+ *     }
+ * }
+ *
+ * @module gulp-mu-gulp-api
+ */
+
+// 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, TimeZoneOffset, InstallStringExtensions, InstallFormatPrototypes, InstallHyphenPrototypes } from './i18x.mjs';
+export { WordHyphenation, Hyphenation, LoadHyphenData } from './i18x-hyphen.mjs';
+import * as I18x from './i18x.mjs';
+
+let uiRequestCounter = 0;
+let ipcListenerAttached = false;
+let lastLoggedPercent = -1;
+const pendingUiRequests = new Map();
+
+/**
+ * @returns {boolean} true when the task runs inside a µGulp worker with an
+ * attached dashboard (progress and inputs are rendered in the webview)
+ */
+export function IsMicroGulp() {
+	// The worker pool sets MICROGULP=1 for every forked task process and
+	// connects an IPC channel (process.send). Child processes spawned from
+	// within a task inherit the env flag but not IPC — they must not be
+	// treated as dashboard workers.
+	return process.env.MICROGULP === '1' && typeof process.send === 'function';
+}
+
+/** Brand-aligned alias for {@link IsMicroGulp}. */
+export const IsµGulp = IsMicroGulp;
+
+/*
+ * Task metadata (µDisplayName, µDescription, µTooltip, µGroup) is localized
+ * the same way as any other i18x phrase: with the context tag written *into*
+ * the source phrase and a String.prototype.i18xRegister() marker so the
+ * i18xe-sync tooling extracts it and the dashboard can translate it later.
+ *
+ *   MAKE_BUILDS.µDisplayName =
+ *       'Make Build V<version/><context="µDisplayName"/>'.i18xRegister();
+ *
+ * i18xRegister() returns the phrase unchanged (the i18x key), so the classic
+ * gulp CLI keeps seeing a plain string while the dashboard translates it via
+ * the merged project dictionary. The prototype is installed by
+ * InstallStringExtensions() (auto-run on import of this module).
+ */
+
+// -------------------------------------------------
+// progress
+// -------------------------------------------------
+
+/**
+ * Reports task progress to the µGulp dashboard (determinate neon progress
+ * bar in the task's sector). CLI fallback: an updating line on a TTY,
+ * 10%-step log lines otherwise.
+ *
+ * @param {number} _value progress in the range 0..1
+ * @param {string} [_label] short status label shown next to the bar
+ */
+export function ReportProgress(_value, _label) {
+	let value = Math.max(0, Math.min(1, Number(_value) || 0));
+	if (IsMicroGulp()) {
+		process.send({ type: 'progress', value, label: _label });
+		return;
+	}
+	let percent = Math.round(value * 100);
+	if (process.stdout.isTTY) {
+		process.stdout.write('\r' + (_label ?? 'progress') + ' ' + percent + '%' + (value >= 1 ? '\n' : ''));
+	} else if (percent >= 100 || percent - lastLoggedPercent >= 10) {
+		lastLoggedPercent = percent >= 100 ? -1 : percent;
+		console.log((_label ?? 'progress') + ' ' + percent + '%');
+	}
+}
+
+/**
+ * Convenience wrapper that carries a fixed label.
+ *
+ * @param {string} [_label]
+ * @returns {{Update: function(number, string=): void, Done: function(): void}}
+ */
+export function CreateProgress(_label) {
+	return {
+		Update(_value, _stepLabel) {
+			ReportProgress(_value, _stepLabel ?? _label);
+		},
+		Done() {
+			ReportProgress(1, _label);
+		},
+	};
+}
+
+function _SendStructuredLog(_format, _payload) {
+	if (!IsMicroGulp()) return false;
+	if (typeof process.send !== 'function') return false;
+	process.send({ type: 'structured-log', format: _format, payload: _payload });
+	return true;
+}
+
+/**
+ * Sends a table to the dashboard log pane. The payload is JSON:
+ * `{ columns: string[] | {id, label}[], rows: (string|number)[][] | object[], hyphenate?: boolean }`.
+ * CLI fallback: a simple ASCII table on stdout.
+ *
+ * @param {object} _spec table descriptor
+ */
+export function LogTable(_spec) {
+	let payload = _NormalizeTableSpec(_spec);
+	if (_SendStructuredLog('table', payload)) return;
+	console.log(_AsciiTable(payload));
+}
+
+/**
+ * Sends a tree structure to the dashboard log pane. The payload is JSON:
+ * `{ label?: string, children?: object[], roots?: object[] }` where each node
+ * has `{ label, children? }`. CLI fallback: indented text lines.
+ *
+ * @param {object} _spec tree descriptor (single root or `{ roots: [...] }`)
+ */
+export function LogTree(_spec) {
+	let payload = _NormalizeTreeSpec(_spec);
+	if (_SendStructuredLog('tree', payload)) return;
+	for (let line of _AsciiTreeLines(payload)) console.log(line);
+}
+
+/**
+ * Sends an image gallery to the dashboard log pane. Each item needs a `src`
+ * (data URI or https URL) and a `label`; optional `caption` and per-item `title`.
+ * CLI fallback: lists labels and src lengths on stdout.
+ *
+ * @param {object} _spec `{ title?, columns?, items: { label, src, caption?, title? }[] }`
+ */
+export function LogGallery(_spec) {
+	let payload = _NormalizeGallerySpec(_spec);
+	if (_SendStructuredLog('gallery', payload)) return;
+	console.log(_AsciiGallery(payload));
+}
+
+/**
+ * Renders µCSS BuildSkin `report.debug.previews` as a thumbnail gallery.
+ * Items without `thumbDataUri` are omitted (paths-only assets stay in the text log).
+ *
+ * @param {object[]} _previews preview entries from `report.debug.previews`
+ * @param {object} [_options] `{ title?, columns? }`
+ */
+export function LogAssetPreviews(_previews, _options = {}) {
+	let items = (_previews ?? [])
+		.filter((_entry) => _entry?.thumbDataUri)
+		.map((_entry) => ({
+			label: String(_entry.relPath ?? _entry.path ?? ''),
+			src: _entry.thumbDataUri,
+			caption: [
+				_entry.step,
+				_entry.skipped ? 'cached' : null,
+				_entry.width && _entry.height ? `${_entry.width}\u00d7${_entry.height}` : null,
+			].filter(Boolean).join(' \u00b7 '),
+		}));
+	if (!items.length) return;
+	LogGallery({
+		title: _options.title,
+		columns: _options.columns ?? 4,
+		items,
+	});
+}
+
+/**
+ * Convenience wrapper for a full µCSS `BuildSkin` debug block: summary table
+ * plus thumbnail gallery when `report.debug` is present.
+ *
+ * @param {object} _report BuildSkin return value
+ * @param {object} [_options] `{ title?, columns?, table?: boolean }`
+ */
+export function LogBuildDebugReport(_report, _options = {}) {
+	let debug = _report?.debug;
+	if (!debug) return;
+	if (_options.table !== false && debug.summary) {
+		LogTable({
+			columns: [{ id: 'metric', label: 'Metric' }, { id: 'value', label: 'Value' }],
+			rows: Object.entries(debug.summary).map(([metric, value]) => ({ metric, value: String(value) })),
+			hyphenate: false,
+		});
+	}
+	LogAssetPreviews(debug.previews, {
+		title: _options.title ?? 'Generated assets',
+		columns: _options.columns,
+	});
+}
+
+/**
+ * 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
+// -------------------------------------------------
+
+/**
+ * Plays an acoustic signal in the µGulp dashboard (WebAudio, respects the
+ * dashboard audio settings: mute/volume). CLI fallback: terminal bell for
+ * 'attention' and 'error' on a TTY, silent otherwise.
+ *
+ * @param {'success'|'error'|'attention'} [_signal]
+ */
+export function PlaySignal(_signal = 'attention') {
+	if (IsMicroGulp()) {
+		process.send({ type: 'sound', signal: _signal });
+		return;
+	}
+	if (process.stdout.isTTY && (_signal === 'attention' || _signal === 'error')) {
+		process.stdout.write('\u0007');
+	}
+}
+
+/**
+ * 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).
+ * CLI fallback: the text is printed as a log line.
+ *
+ * @param {string} _text
+ * @param {object} [_options] { rate?, pitch?, volume? } — per-call overrides (0..2 / 0..2 / 0..1)
+ */
+export function Speak(_text, _options) {
+	let text = String(_text ?? '').trim();
+	if (!text) return;
+	if (IsMicroGulp()) {
+		process.send({ type: 'speech', text, options: _options ?? null });
+		return;
+	}
+	console.log('[speech] ' + text);
+}
+
+// -------------------------------------------------
+// interactive inputs
+// -------------------------------------------------
+
+/**
+ * Requests a complete form from the µGulp dashboard.
+ *
+ * Field descriptor: { id, type, label, default?, options?, validate?,
+ * min?, max?, step?, rows?, placeholder? }
+ *
+ * Supported types: 'text' | 'password' | 'number' | 'textarea' | 'color' |
+ * 'font' | 'select' | 'radio' | 'checkbox' (multi-select, resolves to a
+ * string array) | 'range' (slider with synced number box) | 'date' |
+ * 'time' | 'datetime' | 'file'.
+ *
+ * Options (select/radio/checkbox) accept plain strings or objects
+ * { value, label?, checked?, disabled? }.
+ *
+ * Validation rules: { required?, minLength?, pattern?, minSelected? } —
+ * checks run asynchronously in the webview before submission.
+ *
+ * @param {object} _form { title, fields: [...] }
+ * @returns {Promise<object>} map fieldId -> value
+ */
+export async function RequestForm(_form) {
+	if (IsMicroGulp()) {
+		_EnsureIpcListener();
+		let requestId = 'api-req-' + process.pid + '-' + (++uiRequestCounter);
+		return new Promise((_resolve) => {
+			pendingUiRequests.set(requestId, _resolve);
+			process.send({ type: 'ui-request', requestId, form: _form });
+		});
+	}
+	return _FallbackForm(_form);
+}
+
+/**
+ * Shows a blocking modal message inside the µGulp webview only (info / warning / error).
+ * Opt-in — use when a task needs explicit acknowledgment, not for every log line.
+ * CLI fallback: bracketed console output and `{ button: 'ok' }`.
+ *
+ * @param {object} _spec `{ variant?, title?, message?, buttons?, presentation? }`
+ * @param {'webview'|'ide'|'auto'} [_spec.presentation] `ide` = native host dialog when
+ *   available (VS Code/Cursor); `webview` = in-dashboard glass modal; `auto` = follow host setting
+ * @returns {Promise<{ button: string }>}
+ */
+export async function ShowModalMessage(_spec) {
+	if (IsMicroGulp()) {
+		_EnsureIpcListener();
+		let requestId = 'api-modal-' + process.pid + '-' + (++uiRequestCounter);
+		return new Promise((_resolve) => {
+			pendingUiRequests.set(requestId, _resolve);
+			process.send({ type: 'ui-modal', requestId, modal: _NormalizeModalSpec(_spec) });
+		});
+	}
+	return _FallbackModalMessage(_spec);
+}
+
+/**
+ * @param {object|undefined|null} _spec
+ * @returns {object}
+ */
+function _NormalizeModalSpec(_spec) {
+	let variant = ['info', 'warning', 'error'].includes(_spec?.variant) ? _spec.variant : 'info';
+	let presentation = ['webview', 'ide', 'auto'].includes(_spec?.presentation) ? _spec.presentation : undefined;
+	return {
+		variant,
+		title: _spec?.title != null ? String(_spec.title) : '',
+		message: _spec?.message != null ? String(_spec.message) : '',
+		buttons: Array.isArray(_spec?.buttons) ? _spec.buttons : undefined,
+		presentation,
+	};
+}
+
+/**
+ * @param {object|undefined|null} _spec
+ * @returns {Promise<{ button: string }>}
+ */
+function _FallbackModalMessage(_spec) {
+	let normalized = _NormalizeModalSpec(_spec);
+	console.log(`[modal:${normalized.variant}] ${normalized.title}`.trim());
+	if (normalized.message) console.log(normalized.message);
+	return { button: 'ok' };
+}
+
+/**
+ * Confirmation dialog (Yes/No or OK/Cancel). Wrapper around {@link ShowModalMessage}.
+ *
+ * @param {object} _spec `{ title?, message?, variant?, style?, presentation? }`
+ * @param {'yes-no'|'ok-cancel'} [_spec.style] default `yes-no`
+ * @returns {Promise<{ button: string }>} `yes`, `no`, `ok`, or `cancel`
+ */
+export async function ShowConfirmMessage(_spec) {
+	let style = _spec?.style === 'ok-cancel' ? 'ok-cancel' : 'yes-no';
+	let buttons = style === 'ok-cancel'
+		? [{ id: 'cancel' }, { id: 'ok', primary: true }]
+		: [{ id: 'no' }, { id: 'yes', primary: true }];
+	return ShowModalMessage({
+		variant: _spec?.variant ?? 'warning',
+		title: _spec?.title,
+		message: _spec?.message,
+		presentation: _spec?.presentation,
+		buttons,
+	});
+}
+
+/**
+ * Requests a single validated text value.
+ * @param {object} _options { label, title?, default?, validate? }
+ * @returns {Promise<string|null>}
+ */
+export async function RequestTextInput(_options) {
+	return _SingleField({ ..._options, type: 'text' });
+}
+
+/**
+ * Requests a color (native color picker in the dashboard).
+ * @param {object} _options { label, title?, default? } — default as #rrggbb
+ * @returns {Promise<string|null>}
+ */
+export async function RequestColorInput(_options) {
+	return _SingleField({ ..._options, type: 'color' });
+}
+
+/**
+ * Requests a font selection.
+ * @param {object} _options { label, title?, default?, options? } — options: font family names
+ * @returns {Promise<string|null>}
+ */
+export async function RequestFontInput(_options) {
+	return _SingleField({ ..._options, type: 'font' });
+}
+
+/**
+ * Requests a selection from a fixed option list.
+ * @param {object} _options { label, title?, default?, options: string[] }
+ * @returns {Promise<string|null>}
+ */
+export async function RequestSelectInput(_options) {
+	return _SingleField({ ..._options, type: 'select' });
+}
+
+/**
+ * Requests a multi-selection (checkbox group in the dashboard).
+ * @param {object} _options { label, title?, options: Array<string|{value, label?, checked?, disabled?}>, validate? }
+ * @returns {Promise<string[]>} selected values (empty array when nothing was picked)
+ */
+export async function RequestMultiSelectInput(_options) {
+	let value = await _SingleField({ ..._options, type: 'checkbox' });
+	return Array.isArray(value) ? value : (value != null ? [value] : []);
+}
+
+// -------------------------------------------------
+// internal
+// -------------------------------------------------
+
+function _EnsureIpcListener() {
+	if (ipcListenerAttached) return;
+	ipcListenerAttached = true;
+	process.on('message', (_message) => {
+		if (_message && _message.type === 'ui-response' && pendingUiRequests.has(_message.requestId)) {
+			let resolver = pendingUiRequests.get(_message.requestId);
+			pendingUiRequests.delete(_message.requestId);
+			resolver(_message.payload);
+		}
+	});
+}
+
+async function _SingleField(_options) {
+	let values = await RequestForm({
+		title: _options.title ?? _options.label,
+		fields: [{
+			id: 'value',
+			type: _options.type,
+			label: _options.label,
+			default: _options.default,
+			options: _options.options,
+			validate: _options.validate,
+		}],
+	});
+	return values.value ?? null;
+}
+
+async function _FallbackForm(_form) {
+	let values = {};
+	for (let field of _form.fields ?? []) {
+		values[field.id] = await _FallbackField(field);
+	}
+	return values;
+}
+
+function _NormalizeOptions(_options) {
+	let result = [];
+	for (let option of _options ?? []) {
+		if (option == null) continue;
+		if (typeof option === 'object') {
+			if (option.separator) continue;
+			let value = option.value ?? option.label ?? option.name ?? '';
+			result.push({
+				value: String(value),
+				label: String(option.label ?? option.name ?? value),
+				checked: !!option.checked,
+			});
+		} else {
+			result.push({ value: String(option), label: String(option), checked: false });
+		}
+	}
+	return result;
+}
+
+function _FallbackDefault(_field) {
+	if (_field.type === 'checkbox') {
+		return _NormalizeOptions(_field.options).filter((_option) => _option.checked).map((_option) => _option.value);
+	}
+	return _field.default ?? null;
+}
+
+async function _FallbackField(_field) {
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
+		return _FallbackDefault(_field);
+	}
+	const readline = await import('node:readline/promises');
+	let prompt = readline.createInterface({ input: process.stdin, output: process.stdout });
+	try {
+		let label = _field.label ?? _field.id;
+		let options = _NormalizeOptions(_field.options);
+		let hasOptions = options.length > 0;
+		if (_field.type === 'checkbox' && hasOptions) {
+			options.forEach((_option, _index) => console.log('  [' + (_index + 1) + '] ' + _option.label + (_option.checked ? ' *' : '')));
+			let answer = await prompt.question(label + ' (comma-separated numbers, Enter = defaults marked *): ');
+			let picked = answer.split(',')
+				.map((_part) => parseInt(_part.trim(), 10))
+				.filter((_index) => _index >= 1 && _index <= options.length)
+				.map((_index) => options[_index - 1].value);
+			return picked.length > 0 ? picked : _FallbackDefault(_field);
+		}
+		if ((_field.type === 'select' || _field.type === 'font' || _field.type === 'radio') && hasOptions) {
+			options.forEach((_option, _index) => console.log('  [' + (_index + 1) + '] ' + _option.label));
+			let answer = await prompt.question(label + ' (1-' + options.length + (_field.default ? ', default "' + _field.default + '"' : '') + '): ');
+			let index = parseInt(answer, 10);
+			if (index >= 1 && index <= options.length) return options[index - 1].value;
+			return _field.default ?? null;
+		}
+		let hint = _field.type === 'range' || _field.type === 'number'
+			? ' (' + (_field.min ?? 0) + '-' + (_field.max ?? 100) + (_field.default != null ? ', default ' + _field.default : '') + ')'
+			: (_field.default ? ' [' + _field.default + ']' : '');
+		let answer = await prompt.question(label + hint + ': ');
+		return answer || (_field.default ?? null);
+	} finally {
+		prompt.close();
+	}
+}
+
+function _NormalizeColumn(_column, _index) {
+	if (typeof _column === 'string') return { id: 'c' + _index, label: _column };
+	return { id: String(_column.id ?? 'c' + _index), label: String(_column.label ?? _column.id ?? 'c' + _index) };
+}
+
+function _NormalizeTableSpec(_spec) {
+	let columns = (_spec?.columns ?? []).map(_NormalizeColumn);
+	let rows = _spec?.rows ?? [];
+	let normalizedRows = rows.map((_row) => {
+		if (Array.isArray(_row)) {
+			let obj = {};
+			for (let c = 0; c < columns.length; c++) obj[columns[c].id] = _row[c] ?? '';
+			return obj;
+		}
+		return _row;
+	});
+	return { columns, rows: normalizedRows, hyphenate: _spec?.hyphenate !== false };
+}
+
+function _NormalizeTreeSpec(_spec) {
+	if (_spec?.roots) return { roots: _spec.roots };
+	if (_spec?.label != null || _spec?.children) return { roots: [_spec] };
+	return { roots: [] };
+}
+
+function _AsciiTable(_payload) {
+	let headers = _payload.columns.map((_c) => _c.label);
+	let widths = headers.map((_h) => _h.length);
+	for (let row of _payload.rows) {
+		for (let c = 0; c < _payload.columns.length; c++) {
+			let cell = String(row[_payload.columns[c].id] ?? '');
+			widths[c] = Math.max(widths[c], cell.length);
+		}
+	}
+	let sep = widths.map((_w) => '-'.repeat(_w)).join('-+-');
+	let lines = [headers.map((_h, _i) => _h.padEnd(widths[_i])).join(' | ')];
+	lines.push(sep);
+	for (let row of _payload.rows) {
+		lines.push(_payload.columns.map((_col, _i) => String(row[_col.id] ?? '').padEnd(widths[_i])).join(' | '));
+	}
+	return lines.join('\n');
+}
+
+function _AsciiTreeLines(_payload, _indent = '', _roots = null) {
+	let roots = _roots ?? _payload.roots ?? [];
+	let lines = [];
+	for (let i = 0; i < roots.length; i++) {
+		let node = roots[i];
+		let branch = i < roots.length - 1 ? '├─ ' : '└─ ';
+		lines.push(_indent + branch + String(node.label ?? ''));
+		let childIndent = _indent + (i < roots.length - 1 ? '│  ' : '   ');
+		if (node.children?.length) lines.push(..._AsciiTreeLines(_payload, childIndent, node.children));
+	}
+	return lines;
+}
+
+function _NormalizeGallerySpec(_spec) {
+	let columns = Math.max(1, Math.min(8, Number(_spec?.columns) || 4));
+	let items = (_spec?.items ?? []).map((_item) => ({
+		label: String(_item?.label ?? ''),
+		src: String(_item?.src ?? ''),
+		caption: _item?.caption != null ? String(_item.caption) : '',
+		title: _item?.title != null ? String(_item.title) : '',
+	})).filter((_item) => _item.src);
+	return {
+		title: _spec?.title != null ? String(_spec.title) : '',
+		columns,
+		items,
+	};
+}
+
+function _AsciiGallery(_payload) {
+	let lines = [];
+	if (_payload.title) lines.push(_payload.title);
+	for (let item of _payload.items) {
+		let meta = item.caption ? ` (${item.caption})` : '';
+		let srcHint = item.src.startsWith('data:') ? `[data URI, ${item.src.length} chars]` : item.src;
+		lines.push(`  ${item.label}${meta}: ${srcHint}`);
+	}
+	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;
+}
+
+/**
+ * Asks µGulp to re-evaluate dynamic task metadata (µEnabled predicates,
+ * disabled tooltips) and refresh the dashboard task list. Call after
+ * changing module-level state that drives enable/disable rules.
+ * No-op outside a µGulp worker.
+ */
+export function NotifyTasksChanged() {
+	if (typeof process.send === 'function') {
+		process.send({ type: 'refresh-tasks' });
+	}
+}
+
+export default {
+	IsMicroGulp,
+	IsµGulp,
+	NotifyTasksChanged,
+	ReportProgress,
+	CreateProgress,
+	PlaySignal,
+	PlaySound,
+	StopSound,
+	Speak,
+	RequestForm,
+	RequestTextInput,
+	RequestColorInput,
+	RequestFontInput,
+	RequestSelectInput,
+	RequestMultiSelectInput,
+	Log: I18x.Log,
+	Warn: I18x.Warn,
+	LogError: I18x.LogError,
+	Translate: I18x.Translate,
+	GetLid: I18x.GetLid,
+	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,
+	ShowModalMessage,
+	ShowConfirmMessage,
+	LogKeyValue,
+	LogBadges,
+	LogCode,
+	LogChart,
+};