gulp-mu-gulp-api 0.3.11 → 0.3.13

package/README.md

@@ -37,6 +37,17 @@ 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.
+- **Added** `GetRegisteredDashboardFonts()` / `ClearRegisteredDashboardFonts()` — snapshot / test helpers.
+- Pair with gulpfile metadata `µIcon` (glyph) and optional `µIconFont = '<id>'`, or declarative `export const µDashboardFonts = […]`. Config/setting `dashboardFonts` is an alternative when not using the API.
+- Outside µGulp the helpers are no-ops (fonts are a dashboard/host concern).
+
 ### 0.3.11
 
 - **Added** `ShowModalMessage({ variant?, title?, message?, buttons?, presentation? })` — blocking modal (info/warning/error) in the µGulp dashboard glass panel, or native VS Code/Cursor dialogs when `presentation` is `ide`/`auto` (host setting `microgulp.modalPresentation`).
@@ -89,7 +100,7 @@ npm install gulp-mu-gulp-api
 ## Usage
 
 ```javascript
-import { ReportProgress, CreateProgress, PlaySignal, PlaySound, StopSound, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
+import { ReportProgress, CreateProgress, PlaySignal, PlaySound, StopSound, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, RegisterDashboardFont, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
 
 // Enables "phrase<context=\"…\"/>".i18xRegister()/.i18xTrans() on strings.
 InstallStringExtensions();
@@ -116,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.');
@@ -158,9 +169,12 @@ 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) |
+| `ClearRegisteredDashboardFonts()` | Clears the in-process registry (tests) |
 | `Speak(text, options?)` | Speech output in the dashboard; `options`: `{ rate?, pitch?, volume? }` per-call overrides |
 | `RequestForm(form)` | Request a complete form; resolves with `{ fieldId: value, … }` |
 | `ShowModalMessage(spec)` | Blocking modal (`info`/`warning`/`error`); `presentation`: `webview` \| `ide` \| `auto` |
@@ -194,6 +208,25 @@ MAKE_BUILDS.µDisplayName = 'Make Build V<version/><context="µDisplayName"/>'.i
 // => "Make Build V1.13" in the dashboard (translatable per language)
 ```
 
+### Dashboard fonts (task icons & run log)
+
+Project fonts are independent of the dashboard skin. Register them at gulpfile load time:
+
+```javascript
+import { RegisterDashboardFont } from 'gulp-mu-gulp-api';
+
+RegisterDashboardFont({
+    id: 'ProjectIcons',
+    file: 'assets/task-icons.woff2', // relative to the gulpfile directory
+    usage: 'task-icons',             // or 'log' / 'all'
+});
+
+BUILD.µIcon = '\uE101';
+BUILD.µIconFont = 'ProjectIcons';   // optional when only one task-icons font is registered
+```
+
+Alternatively export `µDashboardFonts` from the gulpfile, or set `dashboardFonts` in `microgulp.config.json` / the `microgulp.dashboardFonts` extension setting. Files must stay under the workspace (`woff2` / `woff` / `ttf` / `otf`). The first `task-icons` font becomes the default for glyph `µIcon` entries; `usage: 'log'` restyles the run-sector log.
+
 ### Field types (for `RequestForm`)
 
 A field descriptor is `{ id, type, label, default?, options?, validate?, min?, max?, step?, rows?, placeholder? }`.
@@ -281,6 +314,17 @@ 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.
+- **Neu** `GetRegisteredDashboardFonts()` / `ClearRegisteredDashboardFonts()` — Snapshot- bzw. Test-Helfer.
+- Zusammen mit Metadaten `µIcon` (Glyph) und optional `µIconFont = '<id>'`, oder deklarativ `export const µDashboardFonts = […]`. Alternative: `dashboardFonts` in Config/Setting.
+- Außerhalb von µGulp sind die Helfer No-ops (Fonts sind Sache von Dashboard/Host).
+
 ### 0.3.11
 
 - **Neu** `ShowModalMessage({ variant?, title?, message?, buttons?, presentation? })` — blockierendes Modal (info/warning/error) als Dashboard-Glaspanel oder natives VS-Code-/Cursor-Dialogfenster bei `presentation` `ide`/`auto` (Host-Setting `microgulp.modalPresentation`).
@@ -333,7 +377,7 @@ npm install gulp-mu-gulp-api
 ## Verwendung
 
 ```javascript
-import { ReportProgress, CreateProgress, PlaySignal, PlaySound, StopSound, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
+import { ReportProgress, CreateProgress, PlaySignal, PlaySound, StopSound, Speak, RequestTextInput, RequestColorInput, RequestFontInput, RequestSelectInput, RequestMultiSelectInput, RequestForm, RegisterDashboardFont, IsMicroGulp, IsµGulp, InstallStringExtensions } from 'gulp-mu-gulp-api';
 
 // Enables "phrase<context=\"…\"/>".i18xRegister()/.i18xTrans() on strings.
 InstallStringExtensions();
@@ -360,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.');
@@ -402,9 +446,12 @@ 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) |
+| `ClearRegisteredDashboardFonts()` | Leert die In-Process-Registry (Tests) |
 | `Speak(text, options?)` | Sprachausgabe im Dashboard; `options`: `{ rate?, pitch?, volume? }` je Aufruf |
 | `RequestForm(form)` | Komplettes Formular anfordern; löst mit `{ fieldId: value, … }` auf |
 | `ShowModalMessage(spec)` | Blockierendes Modal (`info`/`warning`/`error`); `presentation`: `webview` \| `ide` \| `auto` |
@@ -438,6 +485,25 @@ MAKE_BUILDS.µDisplayName = 'Make Build V<version/><context="µDisplayName"/>'.i
 // => „Make Build V1.13“ im Dashboard (pro Sprache übersetzbar)
 ```
 
+### Dashboard-Fonts (Task-Icons & Run-Log)
+
+Projekt-Fonts sind unabhängig vom Dashboard-Skin. Beim Laden des Gulpfiles registrieren:
+
+```javascript
+import { RegisterDashboardFont } from 'gulp-mu-gulp-api';
+
+RegisterDashboardFont({
+    id: 'ProjectIcons',
+    file: 'assets/task-icons.woff2', // relativ zum Gulpfile-Ordner
+    usage: 'task-icons',             // oder 'log' / 'all'
+});
+
+BUILD.µIcon = '\uE101';
+BUILD.µIconFont = 'ProjectIcons';   // optional, wenn nur ein task-icons-Font registriert ist
+```
+
+Alternativ `µDashboardFonts` aus dem Gulpfile exportieren oder `dashboardFonts` in `microgulp.config.json` / Setting `microgulp.dashboardFonts`. Dateien müssen unter dem Workspace liegen (`woff2` / `woff` / `ttf` / `otf`). Der erste `task-icons`-Font ist Default für Glyph-`µIcon`; `usage: 'log'` setzt die Run-Log-Schrift.
+
 ### Feldtypen (für `RequestForm`)
 
 Ein Feld-Deskriptor ist `{ id, type, label, default?, options?, validate?, min?, max?, step?, rows?, placeholder? }`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gulp-mu-gulp-api",
-	"version": "0.3.11",
+	"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`)
  */
@@ -800,10 +806,62 @@ export function NotifyTasksChanged() {
 	}
 }
 
+// -------------------------------------------------
+// dashboard fonts (task icons / run log)
+// -------------------------------------------------
+
+/** @type {Map<string, { id: string, file: string, family?: string, usage?: string|string[] }>} */
+const registeredDashboardFonts = new Map();
+
+/**
+ * Registers a project font for the µGulp dashboard. Call at gulpfile load
+ * time (top-level). The scan worker forwards the registry to the engine;
+ * the host serves the file into the webview / HTTP dashboard.
+ *
+ * @param {object} _spec
+ * @param {string} _spec.id stable id (also default CSS `font-family`)
+ * @param {string} _spec.file path relative to the gulpfile directory (or absolute under the workspace)
+ * @param {string} [_spec.family] CSS font-family name (default: id)
+ * @param {string|string[]} [_spec.usage] `'task-icons'`, `'log'`, or `'all'` (default: task-icons)
+ *
+ * @example
+ * RegisterDashboardFont({ id: 'ProjectIcons', file: 'assets/icons.woff2', usage: 'task-icons' });
+ * BUILD.µIcon = '\uE001';
+ * BUILD.µIconFont = 'ProjectIcons'; // optional when only one task-icons font is registered
+ */
+export function RegisterDashboardFont(_spec) {
+	if (_spec == null || typeof _spec !== 'object') return;
+	let id = String(_spec.id ?? '').trim();
+	if (!id) return;
+	let file = String(_spec.file ?? _spec.path ?? '').trim();
+	if (!file) return;
+	let entry = { id, file };
+	if (_spec.family != null) entry.family = String(_spec.family);
+	if (_spec.usage != null) entry.usage = _spec.usage;
+	registeredDashboardFonts.set(id, entry);
+}
+
+/**
+ * Snapshot of fonts registered via {@link RegisterDashboardFont} in this
+ * process (used by the µGulp scan worker). Safe to call outside µGulp.
+ * @returns {object[]}
+ */
+export function GetRegisteredDashboardFonts() {
+	return [...registeredDashboardFonts.values()].map((_entry) => ({ ..._entry }));
+}
+
+/** Clears the in-process registry (tests). */
+export function ClearRegisteredDashboardFonts() {
+	registeredDashboardFonts.clear();
+}
+
 export default {
 	IsMicroGulp,
 	IsµGulp,
 	NotifyTasksChanged,
+	RegisterDashboardFont,
+	GetRegisteredDashboardFonts,
+	ClearRegisteredDashboardFonts,
 	ReportProgress,
 	CreateProgress,
 	PlaySignal,