[UPDATED] update documentation

Author: thevpc

METADATA

@@ -1,4 +1,4 @@
-buildTime=2026-09-01-182510
+buildTime=2026-09-01-194835
 
 stableApiId=
 stableApiVersion=0.8.9

docs/METADATA

@@ -1,4 +1,4 @@
-buildTime=2026-09-01-182510
+buildTime=2026-09-01-194835
 
 stableApiId=
 stableApiVersion=0.8.9

docs/apps.html

@@ -1,11 +1,11 @@
 /* common.js (templated by nsite) */
-var buildTime = "$2026-09-01-182510";
-var latestJarLocation = "$https://maven.thevpc.net/net/thevpc/nuts/nuts-app/1.0.0/nuts-app-1.0.0.jar";
-var apiVersion = "$1.0.0";
-var runtimeVersion = "$1.0.0.0";
+var buildTime = "2026-09-01-194835";
+var latestJarLocation = "https://maven.thevpc.net/net/thevpc/nuts/nuts-app/1.0.0/nuts-app-1.0.0.jar";
+var apiVersion = "1.0.0";
+var runtimeVersion = "1.0.0.0";
 
-var stableJarLocation = "$https://maven.thevpc.net/net/thevpc/nuts/nuts-app/0.8.9/nuts-app-0.8.9.jar";
-var stableApiVersion = "$0.8.9";
-var stableRuntimeVersion = "$0.8.9.0";
+var stableJarLocation = "https://maven.thevpc.net/net/thevpc/nuts/nuts-app/0.8.9/nuts-app-0.8.9.jar";
+var stableApiVersion = "0.8.9";
+var stableRuntimeVersion = "0.8.9.0";
 
 document.getElementById('build-time').textContent = buildTime;

docs/assets/js/common.js

@@ -1,11 +1,11 @@
 /* nuts-download.js — 3-step download wizard (templated by nsite) */
-// var latestJarLocation = "$https://maven.thevpc.net/net/thevpc/nuts/nuts-app/1.0.0/nuts-app-1.0.0.jar";
-// var apiVersion = "$1.0.0";
-// var runtimeVersion = "$1.0.0.0";
+// var latestJarLocation = "https://maven.thevpc.net/net/thevpc/nuts/nuts-app/1.0.0/nuts-app-1.0.0.jar";
+// var apiVersion = "1.0.0";
+// var runtimeVersion = "1.0.0.0";
 //
-// var stableJarLocation = "$https://maven.thevpc.net/net/thevpc/nuts/nuts-app/0.8.9/nuts-app-0.8.9.jar";
-// var stableApiVersion = "$0.8.9";
-// var stableRuntimeVersion = "$0.8.9.0";
+// var stableJarLocation = "https://maven.thevpc.net/net/thevpc/nuts/nuts-app/0.8.9/nuts-app-0.8.9.jar";
+// var stableApiVersion = "0.8.9";
+// var stableRuntimeVersion = "0.8.9.0";
 
 (function () {
     'use strict';

docs/assets/js/nuts-download.js

@@ -379,7 +379,7 @@ <h6 class="dropdown-header text-uppercase small text-muted">Documentation Versio
                 <li class="nav-item">
                     <a class="nav-link" href="#U3eed099ec964fcd479b51978c3bc72511423c77e">
                         <span class="nav-num">7</span>
-                        07-ansi-theme.md
+                        ANSI Theme Customization
                     </a>
 
 
@@ -2166,28 +2166,79 @@ <h3 class="main-section2">
 
                     <h2 class="main-section1" data-num="7">
                         <a href="#U3eed099ec964fcd479b51978c3bc72511423c77e">
-                            7 07-ansi-theme.md
+                            7 ANSI Theme Customization
                         </a>
                     </h2>
 
                     <div class="text-card">
-                        <H4 class="md-title-1">Customizing ANSI Themes</H4><H4 class="md-title-2">Overview</H4><p class="md-phrase">Nuts provides a powerful theming system for ANSI/NTF (Nuts Text Format) output. Themes determine the actual colors used for semantic tokens such as <mark class="md-code md-code-ac1">primary1</mark>, <mark class="md-code md-code-ac1">error</mark>, <mark class="md-code md-code-ac1">warn</mark>, etc. You can switch between built‑in themes or create your own.</p><H4 class="md-title-2">Switching Themes at Runtime</H4><pre><code class="language-java">import net.thevpc.nuts.text.NTextTheme;
-
-// Load a theme by its name (e.g., &quot;dark&quot;, &quot;light&quot;, &quot;horizon&quot;)
-NTextTheme theme = NTextTheme.of(&quot;dark&quot;);
-// Apply the theme globally
-Nuts.textTheme().setTheme(theme);
-</code></pre>You can also set the theme via a configuration property or environment variable:<ul class="md-ul"><li class="md-uli"><p class="md-phrase"><b class="md-bold">Configuration property</b>: <code class="md-code md-code-ac1">nuts.text.theme = dark</code></p></li><li class="md-uli"><p class="md-phrase"><b class="md-bold">Environment variable</b>: <code class="md-code md-code-ac1">NUTS_TEXT_THEME=dark</code></p></li></ul><H4 class="md-title-2">Defining Your Own Theme</H4><p class="md-phrase">Create a <code class="md-code md-code-ac1">.ntf-theme</code> file in any location accessible to your application. The file format is a simple <code class="md-code md-code-ac1">key=value</code> list where keys are semantic token names and values are color specifications.</p><pre><code class="language-properties"># example.ntf-theme
-primary1 = #1e90ff
-secondary5 = #ffdead
-error = #ff5555
-warn = #ffb86c
-info = #8be9fd
-</code></pre><p class="md-phrase">Place your custom theme file on the classpath (e.g., <code class="md-code md-code-ac1">src/main/resources/META-INF/ntf-themes/</code>) or load it explicitly:</p><pre><code class="language-java">NTextTheme custom = NTextTheme.load(&quot;classpath:/my-theme.ntf-theme&quot;);
-Nuts.textTheme().setTheme(custom);
-</code></pre><H4 class="md-title-2">Built‑in Theme Examples</H4>The repository ships a few example themes you can use as a starting point:<ul class="md-ul"><li class="md-uli"><p class="md-phrase"><b class="md-bold">example.ntf-theme</b> – a balanced default theme.</p></li><li class="md-uli"><p class="md-phrase"><b class="md-bold">horizon.ntf-theme</b> – a dark blue horizon style.</p></li><li class="md-uli"><p class="md-phrase"><b class="md-bold">min.ntf-theme</b> – a minimalistic light theme.</p></li></ul><p class="md-phrase">You can find these files under <code class="md-code md-code-ac1">src/resources/theme-examples/</code>.</p><H4 class="md-title-2">Applying Themes to Specific Output</H4><p class="md-phrase">If you need to render a message with a non‑global theme, use the <mark class="md-code md-code-ac1">NText</mark> API directly:</p><pre><code class="language-java">NText themed = NText.of(&quot;Hello World&quot;).withTheme(custom);
-NOut.println(themed);
-</code></pre><H4 class="md-title-2">Further Reading</H4><ul class="md-ul"><li class="md-uli"><p class="md-phrase"><mark class="md-code md-code-ac1">NTextTheme</mark> class: <code class="md-code md-code-ac1">net.thevpc.nuts.text.NTextTheme</code></p></li><li class="md-uli"><p class="md-phrase">Default runtime implementation: <code class="md-code md-code-ac1">net.thevpc.nuts.runtime.standalone.text.DefaultNTextRPI</code></p></li><li class="md-uli"><p class="md-phrase">Theme resource location: <code class="md-code md-code-ac1">META-INF/ntf-themes/</code></p></li></ul><p class="md-phrase">For more details, refer to the <a href="../03-msg/02-nmsg-styling.md" class="md-link">Styling Messages</a> section.</p>
+                        <H4 class="md-title-1">Customizing ANSI Themes</H4><H4 class="md-title-2">Overview</H4><p class="md-phrase">Nuts provides a powerful theming system for ANSI and NTF (Nuts Text Format) formatted output. Themes map semantic text styles (such as <mark class="md-code md-code-ac1">PRIMARY</mark>, <mark class="md-code md-code-ac1">KEYWORD</mark>, <mark class="md-code md-code-ac1">ERROR</mark>, <mark class="md-code md-code-ac1">WARN</mark>, <mark class="md-code md-code-ac1">INFO</mark>, <mark class="md-code md-code-ac1">PATH</mark>, etc.) to specific terminal colors, supporting 16-color ANSI, 256-color palettes, and 24-bit RGB true-colors.</p><p class="md-phrase">The <mark class="md-code md-code-ac1">--theme</mark> option and the <mark class="md-code md-code-ac1">NTextTheme</mark> API support specifying theme parameters by <b class="md-bold">theme name</b> (for built-in or cached themes) or by <b class="md-bold">file path / URL</b> (for custom <code class="md-code md-code-ac1">.ntf-theme</code> files).</p><H4 class="md-title-2">Built-in Themes & Default Names</H4><p class="md-phrase">Nuts includes several built-in themes available on the classpath (<code class="md-code md-code-ac1">META-INF/ntf-themes/</code>). You can reference them directly by name:</p><ul class="md-ul"><li class="md-uli"><p class="md-phrase"><b class="md-bold"><mark class="md-code md-code-ac1">default</mark></b> – OS-dependent default theme (<mark class="md-code md-code-ac1">grass</mark> on Windows, standard theme on Unix/Linux).</p></li><li class="md-uli"><p class="md-phrase"><b class="md-bold"><mark class="md-code md-code-ac1">ansi</mark></b> – Basic 16-color ANSI palette theme.</p></li><li class="md-uli"><p class="md-phrase"><b class="md-bold"><mark class="md-code md-code-ac1">grass</mark></b> – Green/nature-toned palette, optimized for Windows terminals.</p></li><li class="md-uli"><p class="md-phrase"><b class="md-bold"><mark class="md-code md-code-ac1">horizon</mark></b> – Dark blue horizon theme, default on Unix/Linux.</p></li><li class="md-uli"><p class="md-phrase"><b class="md-bold"><mark class="md-code md-code-ac1">whiteboard</mark></b> – Light background theme using 24-bit true colors.</p></li></ul><p class="md-phrase">When no theme name or path is provided (or when set to <mark class="md-code md-code-ac1">default</mark>), Nuts automatically selects the appropriate default theme for the running operating system environment.</p><H4 class="md-title-2">Setting Themes at Boot or Runtime</H4><H4 class="md-title-3"><p class="md-phrase">Via Command Line Option (<mark class="md-code md-code-ac1">--theme</mark>)</p></H4><p class="md-phrase">The <mark class="md-code md-code-ac1">--theme</mark> CLI option accepts either a built-in theme name or a file path/URL to a custom theme file.</p><H4 class="md-title-4">1. By Theme Name</H4><p class="md-phrase">Pass one of the default theme names (<mark class="md-code md-code-ac1">default</mark>, <mark class="md-code md-code-ac1">ansi</mark>, <mark class="md-code md-code-ac1">grass</mark>, <mark class="md-code md-code-ac1">horizon</mark>, <mark class="md-code md-code-ac1">whiteboard</mark>):</p><pre><code class="language-sh">nuts --theme=horizon
+</code></pre><H4 class="md-title-4">2. By File Path or URL</H4><p class="md-phrase">Pass a file path (relative or absolute) or URL to a <code class="md-code md-code-ac1">.ntf-theme</code> file:</p><pre><code class="language-sh">nuts --theme=/path/to/my-theme.ntf-theme
+</code></pre><H4 class="md-title-3">Via Java API</H4><p class="md-phrase">The <code class="md-code md-code-ac1">NTextTheme.of(String nameOrPath)</code> factory method resolves themes seamlessly:</p><ul class="md-ul"><li class="md-uli"><p class="md-phrase"><b class="md-bold">Simple Name</b>: Loads built-in theme resources from <code class="md-code md-code-ac1">classpath:/META-INF/ntf-themes/&lt;name&gt;.ntf-theme</code> or user themes from <code class="md-code md-code-ac1">~/.config/nuts/.../themes/&lt;name&gt;</code>. Themes loaded by name are cached.</p></li><li class="md-uli"><p class="md-phrase"><b class="md-bold">File Path or URL</b>: Loads the theme from the specified filesystem path or URL via <mark class="md-code md-code-ac1">NPath</mark>.</p></li><li class="md-uli"><p class="md-phrase"><b class="md-bold">Null or Blank</b>: Loads the default theme configured for the workspace/OS environment.</p></li></ul><H4 class="md-title-4">Example Usage</H4><pre><code class="language-java">import net.thevpc.nuts.text.NTextTheme;
+import net.thevpc.nuts.io.NPath;
+
+// Load a theme by built-in name
+NTextTheme themeByName = NTextTheme.of(&quot;horizon&quot;).orNull();
+if (themeByName != null) {
+    NTextTheme.set(themeByName);
+}
+
+// Load a theme by file path
+NTextTheme themeByPath = NTextTheme.of(&quot;/path/to/my-theme.ntf-theme&quot;).orNull();
+if (themeByPath != null) {
+    NTextTheme.set(themeByPath);
+}
+
+// Using NPath explicitly
+NTextTheme themeFromNPath = NTextTheme.of(NPath.of(&quot;/path/to/my-theme.ntf-theme&quot;)).orNull();
+</code></pre><H4 class="md-title-2">Defining Your Own Theme</H4><p class="md-phrase">Themes are defined in <code class="md-code md-code-ac1">.ntf-theme</code> property files. A theme file consists of key-value pairs defining: 1. Optional theme metadata (e.g. <code class="md-code md-code-ac1">theme-name=my-theme</code>). 2. Optional custom color/palette variables (e.g., <code class="md-code md-code-ac1">MY_BLUE=4</code>, <code class="md-code md-code-ac1">DARK_RED=#670000</code>). 3. Mapping rules for semantic token styles.</p><H4 class="md-title-3">Syntax & Format</H4><pre><code class="language-properties"># example.ntf-theme
+theme-name=my-theme
+
+# Palette variables (ANSI numbers 0-255 or 24-bit hex colors)
+DARK_BLUE=4
+BRIGHT_BLUE=12
+DARK_SKY=6
+DARK_RED=#670000
+
+# Primary and Secondary base palette styles with variant index
+PRIMARY(0)=foregroundColor(DARK_BLUE)
+PRIMARY(1)=foregroundColor(BRIGHT_BLUE)
+PRIMARY(*)=PRIMARY(*%16)
+
+SECONDARY(0)=backgroundColor(DARK_BLUE)
+SECONDARY(*)=SECONDARY(*%16)
+
+# Title style combining primary and underline
+TITLE(*)=primary(*),underlined()
+
+# Syntax &amp; Token Styles
+KEYWORD(0)=foregroundColor(BRIGHT_BLUE)
+KEYWORD(1)=foregroundColor(DARK_SKY)
+KEYWORD(*)=KEYWORD(*%4)
+
+OPTION(0)=foregroundColor(DARK_SKY)
+OPTION(*)=KEYWORD(*%4)
+
+# Semantic UI &amp; Status Styles
+ERROR(*)=foregroundColor(DARK_RED)
+SUCCESS(*)=foregroundColor(2)
+WARN(*)=foregroundColor(3)
+INFO(*)=foregroundColor(DARK_SKY)
+CONFIG(*)=foregroundColor(5)
+DATE(*)=foregroundColor(6)
+NUMBER(*)=foregroundColor(6)
+BOOLEAN(*)=foregroundColor(6)
+STRING(*)=foregroundColor(8)
+SEPARATOR(*)=foregroundColor(208)
+OPERATOR(*)=foregroundColor(208)
+INPUT(*)=foregroundColor(11)
+FAIL(*)=foregroundColor(DARK_RED)
+DANGER(*)=foregroundColor(DARK_RED)
+VAR(*)=foregroundColor(190)
+PALE(*)=foregroundColor(250)
+COMMENTS(*)=foregroundColor(250)
+VERSION(*)=foregroundColor(220)
+PATH(*)=foregroundColor(114)
+</code></pre><H4 class="md-title-3">Supported Token Styles</H4>Supported semantic style tokens include:<ul class="md-ul"><li class="md-uli"><p class="md-phrase">Base: <mark class="md-code md-code-ac1">PRIMARY</mark>, <mark class="md-code md-code-ac1">SECONDARY</mark>, <mark class="md-code md-code-ac1">TITLE</mark></p></li><li class="md-uli"><p class="md-phrase">Syntax: <mark class="md-code md-code-ac1">KEYWORD</mark>, <mark class="md-code md-code-ac1">ENTITY</mark>, <mark class="md-code md-code-ac1">ACTION</mark>, <mark class="md-code md-code-ac1">ANNOTATION</mark>, <mark class="md-code md-code-ac1">VAR</mark>, <mark class="md-code md-code-ac1">OPERATOR</mark>, <mark class="md-code md-code-ac1">SEPARATOR</mark>, <mark class="md-code md-code-ac1">COMMENTS</mark></p></li><li class="md-uli"><p class="md-phrase">Literals: <mark class="md-code md-code-ac1">STRING</mark>, <mark class="md-code md-code-ac1">INPUT</mark>, <mark class="md-code md-code-ac1">PATH</mark>, <mark class="md-code md-code-ac1">VERSION</mark>, <mark class="md-code md-code-ac1">NUMBER</mark>, <mark class="md-code md-code-ac1">DATE</mark>, <mark class="md-code md-code-ac1">BOOLEAN</mark>, <mark class="md-code md-code-ac1">OPTION</mark>, <mark class="md-code md-code-ac1">PLACEHOLDER</mark></p></li><li class="md-uli"><p class="md-phrase">UI Status: <mark class="md-code md-code-ac1">INFO</mark>, <mark class="md-code md-code-ac1">CONFIG</mark>, <mark class="md-code md-code-ac1">SUCCESS</mark>, <mark class="md-code md-code-ac1">WARN</mark>, <mark class="md-code md-code-ac1">ERROR</mark>, <mark class="md-code md-code-ac1">DANGER</mark>, <mark class="md-code md-code-ac1">FAIL</mark>, <mark class="md-code md-code-ac1">PALE</mark></p></li></ul><H4 class="md-title-3">Supported Styling Functions</H4><ul class="md-ul"><li class="md-uli"><p class="md-phrase">Modifiers: <mark class="md-code md-code-ac1">plain</mark>, <mark class="md-code md-code-ac1">underlined</mark>, <mark class="md-code md-code-ac1">bold</mark>, <mark class="md-code md-code-ac1">blink</mark>, <mark class="md-code md-code-ac1">striked</mark>, <mark class="md-code md-code-ac1">reversed</mark>, <mark class="md-code md-code-ac1">italic</mark></p></li><li class="md-uli"><p class="md-phrase">Colors: <code class="md-code md-code-ac1">foregroundColor(val)</code> / <code class="md-code md-code-ac1">foreground(val)</code>, <code class="md-code md-code-ac1">backgroundColor(val)</code> / <code class="md-code md-code-ac1">background(val)</code>, <code class="md-code md-code-ac1">foregroundTrueColor(val)</code>, <code class="md-code md-code-ac1">backgroundTrueColor(val)</code> or direct <code class="md-code md-code-ac1">#RRGGBB</code> hex values.</p></li></ul><H4 class="md-title-3">Custom Theme Locations</H4><p class="md-phrase">Place custom theme files in: 1. The application classpath under <code class="md-code md-code-ac1">META-INF/ntf-themes/&lt;name&gt;.ntf-theme</code>. 2. The Nuts user configuration directory under <code class="md-code md-code-ac1">~/.config/nuts/.../themes/&lt;name&gt;</code>. 3. Any accessible filesystem location loaded by path or URL using <code class="md-code md-code-ac1">--theme=/path/to/theme.ntf-theme</code> or <code class="md-code md-code-ac1">NTextTheme.of(NPath.of(...))</code>.</p><H4 class="md-title-2">Further Reading</H4><ul class="md-ul"><li class="md-uli"><p class="md-phrase"><mark class="md-code md-code-ac1">NTextTheme</mark> interface: <code class="md-code md-code-ac1">net.thevpc.nuts.text.NTextTheme</code></p></li><li class="md-uli"><p class="md-phrase">Default theme implementation: <code class="md-code md-code-ac1">net.thevpc.nuts.runtime.standalone.text.theme.NTextPropertiesTheme</code></p></li><li class="md-uli"><p class="md-phrase">Built-in theme resources: <code class="md-code md-code-ac1">META-INF/ntf-themes/</code></p></li></ul><p class="md-phrase">For more details, refer to the <a href="../03-msg/02-nmsg-styling.md" class="md-link">Styling Messages</a> section.</p>
                     </div>