gulp-mu-gulp-api 0.3.12 → 0.3.13

package/README.md

@@ -37,6 +37,10 @@ The module is deliberately **dependency-free** and knows nothing about µGulp™
 npm install gulp-mu-gulp-api
 ```
 
+### 0.3.13
+
+- **Updated** `PlaySignal` / `PlaySound` docs and CLI fallbacks for the µGulp sound schema (`taskSuccess`, `taskFailed`, `requestAlert`, …). Legacy presets `success` / `error` / `attention` remain valid.
+
 ### 0.3.12
 
 - **Added** `RegisterDashboardFont({ id, file, family?, usage? })` — registers a workspace font for µGulp dashboard **task icons** and/or **run-log** typography. `usage`: `'task-icons'` (default), `'log'`, or `'all'`. Call at gulpfile load time; the scan worker forwards the registry to the engine.
@@ -123,8 +127,8 @@ export async function BUILD_THEME() {
     progress.Done();
 
     // sound + speech (rendered by the dashboard, configured in its settings)
-    PlaySignal('success');              // preset: success | error | attention
-    PlaySound('success');               // named atlas sample
+    PlaySignal('success');              // preset → taskSuccess (also error→taskFailed, attention→requestAlert)
+    PlaySound('taskSuccess');           // named atlas sample (see MicroGulpSoundSchema.md)
     PlaySound('engine', { loop: true }); // loop until StopSound('engine')
     StopSound('engine');
     Speak('Theme build finished.');
@@ -165,8 +169,8 @@ let values = await RequestForm({
 | `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?)` | Preset acoustic signal: `'success'` \| `'error'` \| `'attention'` (default) |
-| `PlaySound(sample, options?)` | Named sample from the dashboard sound atlas; `options.loop` repeats until `StopSound` |
+| `PlaySignal(signal?)` | Preset or schema name; presets: `'success'`→`taskSuccess`, `'error'`→`taskFailed`, `'attention'`→`requestAlert` |
+| `PlaySound(sample, options?)` | Named sample from the dashboard sound atlas (e.g. `taskStart`, `requestInfo`); `options.loop` repeats until `StopSound` |
 | `StopSound(sample)` | Stops a looping sample started with `PlaySound(sample, { loop: true })` |
 | `RegisterDashboardFont(spec)` | Registers a workspace font for dashboard task icons / run-log (`id`, `file`, optional `family` / `usage`: `task-icons`\|`log`\|`all`) |
 | `GetRegisteredDashboardFonts()` | Snapshot of fonts registered in this process (scan worker / tests) |
@@ -310,6 +314,10 @@ Das Modul ist bewusst **abhängigkeitsfrei** und kennt keine µGulp™-Interna:
 npm install gulp-mu-gulp-api
 ```
 
+### 0.3.13
+
+- **Aktualisiert** `PlaySignal` / `PlaySound` für das µGulp-Sound-Schema (`taskSuccess`, `taskFailed`, `requestAlert`, …). Legacy-Presets `success` / `error` / `attention` bleiben gültig.
+
 ### 0.3.12
 
 - **Neu** `RegisterDashboardFont({ id, file, family?, usage? })` — registriert einen Workspace-Font für **Task-Icons** und/oder die **Run-Log**-Typografie im µGulp-Dashboard. `usage`: `'task-icons'` (Default), `'log'` oder `'all'`. Aufruf beim Laden des Gulpfiles; der Scan-Worker reicht die Registry an die Engine weiter.
@@ -396,8 +404,8 @@ export async function BUILD_THEME() {
     progress.Done();
 
     // sound + speech (rendered by the dashboard, configured in its settings)
-    PlaySignal('success');              // preset: success | error | attention
-    PlaySound('success');               // named atlas sample
+    PlaySignal('success');              // preset → taskSuccess (also error→taskFailed, attention→requestAlert)
+    PlaySound('taskSuccess');           // named atlas sample (see MicroGulpSoundSchema.md)
     PlaySound('engine', { loop: true }); // loop until StopSound('engine')
     StopSound('engine');
     Speak('Theme build finished.');
@@ -438,8 +446,8 @@ let values = await RequestForm({
 | `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?)` | Vorgabe-Signal: `'success'` \| `'error'` \| `'attention'` (Default) |
-| `PlaySound(sample, options?)` | Benanntes Sample aus dem Sound-Atlas; `options.loop` wiederholt bis `StopSound` |
+| `PlaySignal(signal?)` | Vorgabe oder Schema-Name; Presets: `'success'`→`taskSuccess`, `'error'`→`taskFailed`, `'attention'`→`requestAlert` |
+| `PlaySound(sample, options?)` | Benanntes Sample aus dem Sound-Atlas (z. B. `taskStart`, `requestInfo`); `options.loop` wiederholt bis `StopSound` |
 | `StopSound(sample)` | Stoppt eine Schleife von `PlaySound(sample, { loop: true })` |
 | `RegisterDashboardFont(spec)` | Registriert einen Workspace-Font für Dashboard-Task-Icons / Run-Log (`id`, `file`, optional `family` / `usage`: `task-icons`\|`log`\|`all`) |
 | `GetRegisteredDashboardFonts()` | Snapshot der in diesem Prozess registrierten Fonts (Scan-Worker / Tests) |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gulp-mu-gulp-api",
-	"version": "0.3.12",
+	"version": "0.3.13",
 	"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/index.mjs

@@ -287,29 +287,35 @@ export function LogChart(_spec) {
 /**
  * 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.
+ * 'attention' / 'error' (and their schema aliases) on a TTY, silent otherwise.
  *
- * @param {'success'|'error'|'attention'} [_signal]
+ * Presets map to atlas samples: `success`→`taskSuccess`, `error`→`taskFailed`,
+ * `attention`→`requestAlert`. New schema names (`taskStart`, `requestInfo`, …)
+ * are also accepted.
+ *
+ * @param {string} [_signal]
  */
 export function PlaySignal(_signal = 'attention') {
 	if (IsMicroGulp()) {
 		process.send({ type: 'sound', signal: _signal });
 		return;
 	}
-	if (process.stdout.isTTY && (_signal === 'attention' || _signal === 'error')) {
+	let key = String(_signal ?? '').trim();
+	if (process.stdout.isTTY && (key === 'attention' || key === 'error' || key === 'requestAlert' || key === 'taskFailed')) {
 		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.
+ * the files bundled with µGulp (see `dev/docs/MicroGulpSoundSchema.md`), e.g.
+ * `taskSuccess`, `taskFailed`, `requestAlert`, or custom atlas entries in a
+ * consumer theme pack. 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 {string} _sample atlas sample name (e.g. `'taskSuccess'`)
  * @param {object} [_options]
  * @param {boolean} [_options.loop] repeat until stopped (default `false`)
  */