Introducing AnyPlex

doc/anyplex.md

@@ -0,0 +1,98 @@
+### AnyPlex Protocol (APP)
+
+The **AnyPlex Protocol** allows vector, bitmap, and extensible markup objects to be embedded directly into the terminal's scrollback buffer.
+
+#### Backend & Frontend Separation
+
+The protocol operates on a decoupled architecture to ensure high performance and display adaptability.
+
+Scope                           | Role
+--------------------------------|-----
+**The Backend (BE)**            | Acts as the "Source of Truth". It manages the terminal state, handles the scrollback buffer, and maintains the global object cache. It tracks metadata per cell but remains agnostic of physical pixels.
+**The Graphical Frontend (FE)** | Acts as the "Painter". It performs the actual rasterization of documents (e.g., SVG to pixels) based on local cell metrics. It handles alpha-blending, Z-order layering, and pixel-wise offsets.
+
+#### Rendering & Interaction
+
+- **Rectangular Area**: The object is hosted within a grid of cells defined by `ceil(width)` and `ceil(height)`.
+- **Pixel-wise Precision**: The raster is scaled using floating-point `width` and `height` and positioned with `dx` and `dy` offsets. Offsets are calculated **per-frontend** based on its current cell metrics.
+- **Asynchronous Rasterization**: It is recommended to perform rasterization in a parallel thread. Until the raster is ready, the frontend should display the cells without the graphic.
+- **Persistence**: Metadata is stored per-cell to survive scrollback and ensure that wrapped cell-runs remain logically linked for a strict rectangular reflow.
+- **Cursor Position**: Anchored at the top-left; moves to the cell immediately following the rectangle's bottom-right corner after output.
+- **Destructivity**:
+  - If the **`gc`** attribute is not empty, the provided grapheme cluster is written to **every cell** in the area (`ceil(width)` by `ceil(height)`), replacing existing text and SGR attributes.
+  - If **`gc`** is empty, the output is non-destructive; existing text and SGR attributes remain visually intact under the transparent object.
+  - Any text subsequently written over the object's area does not destroy the underlying object. The object metadata remains intact in the cell until explicitly cleared or replaced.
+- **Selection & SGR 7**: When selecting text/graphics with the mouse, or when the **SGR 7** attribute is present in a cell, the frontend **halves the alpha channel** of the object's pixels within that cell.
+- **Searchability**: Any text contained within the document (e.g., `<text>` in SVG) is treated as part of the graphic and is not required to be indexed by the terminal's text search.
+- **Layering & Transparency**: Supports per-pixel alpha transparency. The `ontop` attribute determines Z-order relative to text (0 = background `[Cell BG] -> [Object] -> [Text]`, 1 = foreground `[Cell BG] -> [Text] -> [Object]`; the cell's background color always remains in the background). The terminal cursor is always drawn on top of everything. Alpha blending is performed in **linear color space**.
+- **Foreground Color**: The underlying cell **SGR foreground color** maps to `currentColor` (for SVG). All other external references (e.g., `http://...`) are ignored for security.
+
+#### Scroll & Reflow Behavior
+
+- **Normal Buffer**: If the cell-run containing the object does not fit within the viewport width, it triggers a standard wrap with a scroll-up if necessary (without triggering **BCE - Background Color Erase**). This may break the rectangular visual of the raster until the viewport is widened or a non-wrap mode is enabled.
+- **Alternate Buffer**: The object's rectangle is strictly clipped (cropped) by the right and bottom edges of the viewport; no scrolling occurs.
+
+#### Sequence Format
+
+```
+ESC ] app ; [<attributes>] [<document>] ST
+```
+
+Field             | Description
+------------------|------------
+**OSC command**   | Mandatory. `app`.
+**attributes**    | Optional. Space-separated `key=value` pairs. Values can be quoted (`"` or `'`) or unquoted. All keys and values are **case-sensitive**.
+**document**      | Optional. UTF-8 data starting with `<` (the first character of the openning tag, e.g. `<svg>`) and ending with `>` (the last character of the closing tag, e.g. `</svg>`). The specified document is considered to be an `empty-doc` if it has the form `<tag></tag>`, where `tag` is any string.
+
+#### Attributes
+
+Attribute     | Values                                 | Default                  | Description
+--------------|----------------------------------------|--------------------------|------------
+**id**        | `<id>[/sub-id]`                        | empty string (`""`)      | Object reference ID.
+**gc**        | `string`                               | empty string (`""`)      | Grapheme cluster to write to cells (will be scaled to a 1x1 cell size).
+**ontop**     | `0`\|`1`                               | `0`                      | 0 = under text, 1 = over text.
+**width**     | `float (0..65535]`                     | Terminal viewport width  | Raster scale width (cells).
+**height**    | `float (0..65535]`                     | Terminal viewport height | Raster scale height (cells).
+**dx**        | `float`                                | `0.0`                    | Horizontal offset of the raster within the grid (cells).
+**dy**        | `float`                                | `0.0`                    | Vertical offset of the raster within the grid (cells).
+**column**    | `0`..`ceil(width)`                     | `0`                      | Horizontal 1-based slicing index for partial rendering (0 = full width, 1..n = specific cell/slice).
+**row**       | `0`..`ceil(height)`                    | `0`                      | Vertical 1-based slicing index for partial rendering (0 = full height, 1..m = specific cell/slice).
+**align**     | \[`left`\|`center`\|`right`\]\[`-`\]\[`top`\|`middle`\|`bottom`\] | `center-middle` | 2D alignment within the rectangle.
+**scale**     | `inside`\|`outside`\|`stretch`\|`none` | `inside`                 | Fit logic (none = exact pixels, cropped if larger).
+**transform** | `0`..`7`                               | `0`                      | 3-bit compact transformation state `[FlipY][FlipX][SwapXY]`.
+**flip**      | `none`\|`v`\|`h`\|`vh`\|`hv`           | `none`                   | Applied in order of appearance in the string.
+**rotate**    | `0`\|`90`\|`180`\|`270`                | `0`                      | CCW rotation applied in order of appearance.
+
+> Notes:
+> - If `id` is omitted , the empty string `id=""` is used for registration and output.
+> - Attribute values `width` and `height` are clamped to the `(0..65535]` range and further limited by the terminal's maximum window size settings.
+> - Attribute values `width`, `height`, `dx` and `dy` are multiplied by the cell size and **rounded** to get the exact pixel values on the FE side.
+> - The first part of the object reference ID (`id`) references the raw object document in the Backend cache.
+> - The second part of the object reference ID (`sub-id`) addresses the specific named element (e.g., an `id="..."` within an SVG document). The Frontend renders only this fragment if it is specified.
+
+#### Lifecycle & Cache Management
+
+Input State             | Action
+------------------------|-------
+**id** + **doc**        | Store/update the object document in cache and output.
+**id** + **empty-doc**  | Unregister `id` and free the index.
+**id** + **no-doc**     | Output cached object.
+**id/sub-id**           | If a `sub-id` is specified, the FE renders that specific element in its original coordinates (as it would appear in the full document), inheriting all parent styles (CSS, `<g>` groups).
+**Errors**              | If a document is invalid, the `id` is unknown, the `sub-id` is missing, or the cache is full, the FE **clears the object metadata** in the target area (rendering nothing) and logs the error.
+
+> Note:
+> When the BE deletes an `id`, or upon `reset`/session close, it frees the index and signals the FEs.
+> - FEs then traverse their viewport cells; any image in the FE cache no longer referenced by any cell is purged.
+> - If an FE encounters an unknown object index in a cell, it must request full metadata/document from the BE.
+
+#### Parsing Rules (Backend)
+
+1. Scan the OSC string for `key=value` pairs.
+2. Identify document boundaries via first `<` and last `>`.
+3. Apply transformation pipeline (`transform`, `flip`, `rotate`) in the order they appear.
+
+#### Extensibility
+
+The protocol is engine-agnostic. Focused on **SVG**, but designed to support other formats (e.g., `<html>`, `<object>`) via root tag identification.
+
+The protocol can be extended to include non-visual data segments such as `<audio>` or `<wav>`, allowing for synchronized multimedia playback managed by the Frontend.

doc/architecture.md

@@ -438,7 +438,7 @@ Note: You can explicitly specify running vtm inside the terminal (run `vtm --tui
 
 - In general, the local and remote platforms may be different.
 - When the DirectVT mode is used, all keyboard, mouse, and other input events are transmitted between hosts in a binary form.
-- The following examples assume that vtm is accessible via PATH on both the local and remote sides. 
+- The following examples assume that vtm is accessible via PATH on both the local and remote sides.
 
 ### Run remote desktop/terminal over SSH
 

doc/character_geometry.md

@@ -159,17 +159,7 @@ VS12 | 0xFE0B    | Rotate 270° CCW
 VS13 | 0xFE0C    | Horizontal flip
 VS14 | 0xFE0D    | Vertical flip
 
-Example functions for applying a rotation operation to the current three-bit integer state:
-```c++
-void VS10(int& state) { state = (state & 0b100) | ((state + 0b001) & 0b011); }
-void VS11(int& state) { state = (state & 0b100) | ((state + 0b010) & 0b011); }
-void VS12(int& state) { state = (state & 0b100) | ((state + 0b011) & 0b011); }
-void VS13(int& state) { state = (state ^ 0b100) | ((state + (state & 1 ? 0 : 0b010)) & 0b011); }
-void VS14(int& state) { state = (state ^ 0b100) | ((state + (state & 1 ? 0b010 : 0)) & 0b011); }
-
-int get_angle(int state) { int angle = 90 * (state & 0b011); return angle; }
-int get_hflip(int state) { int hflip = state >> 2; return hflip; }
-```
+Note: Due to non-commutativity, transformations are performed in the order they appear.
 
 # New Look for Text-based User Interface
 

doc/settings.md

@@ -1003,12 +1003,12 @@ Notes
             <default fgc=whitedk bgc=pureblack/>  <!-- Default terminal colors (SGR 39/49, set by OSC 10/11). -->
             <match fx="color" fgc=whitelt bgc= #007F00/>  <!-- Appearance of selected text matches. Available shaders (fx): "xlight", "color", "invert", "reverse". -->
             <selection>
-                <text      fx="color"  fgc=whitelt bgc=bluelt/>  <!-- Selection highlighting for plaintext clipboard mode. -->
-                <protected fx="color"  fgc=whitelt bgc=bluelt/>  <!-- Note: bgc and fgc attributes only apply when fx="color". -->
-                <ansi      fx="xlight" fgc=whitelt bgc=bluelt/>
-                <rich      fx="xlight" fgc=whitelt bgc=bluelt/>
-                <html      fx="xlight" fgc=whitelt bgc=bluelt/>
-                <none      fx="color"  fgc=whitedk bgc=blacklt/>  <!-- Appearance of an inactive selection. -->
+                <text      fx="color" inv=true bgc=whitelt fgc=bluelt/>  <!-- Selection highlighting for plaintext clipboard mode. -->
+                <protected fx="color" inv=true bgc=whitelt fgc=bluelt/>  <!-- Notes: -->
+                <ansi      fx="color" inv=true bgc=whitelt fgc=bluelt/>  <!--   - inv=true ensures that the embedded image becomes translucent (see AnyPlex Protocol). -->
+                <rich      fx="color" inv=true bgc=whitelt fgc=bluelt/>  <!--   - bgc and fgc attributes only apply when fx="color".            -->
+                <html      fx="color" inv=true bgc=whitelt fgc=bluelt/>
+                <none      fx="color" inv=true bgc=whitedk fgc=blacklt/>  <!-- Appearance of an inactive selection. -->
             </selection>
             <names=/X11ColorNames>  <!-- Color name mappings for OSC 4, 10-12. -->
                 <!--  <name="New Dark Orange" rgb= #FF8C00 /> -->

src/netxs/apps/tile.hpp

@@ -794,14 +794,14 @@ namespace netxs::app::tile
         auto parse_data = [](auto&& parse_data, view& utf8, auto min_ratio, auto grip_bindings_ptr) -> netxs::sptr<ui::veer>
         {
             auto slot_ptr = node_veer(node_veer, min_ratio, grip_bindings_ptr);
-            utf::trim_front(utf8, ", ");
+            utf::trim_front(utf8, netxs::whitespaces_and<','>);
             if (utf8.empty()) return slot_ptr;
             auto tag = utf8.front();
             if ((tag == 'h' || tag == 'v') && utf8.find('(') < utf8.find(','))
             {
                 // add split
                 utf8.remove_prefix(1);
-                utf::trim_front(utf8, ' ');
+                utf::trim_front(utf8, netxs::whitespaces);
                 auto s1 = si32{ 1 };
                 auto s2 = si32{ 1 };
                 auto w  = si32{-1 };
@@ -813,14 +813,14 @@ namespace netxs::app::tile
                     if (auto r = utf::to_int(utf8)) // Right side ratio
                     {
                         s2 = std::abs(r.value());
-                        utf::trim_front(utf8, ' ');
+                        utf::trim_front(utf8, netxs::whitespaces);
                         if (!utf8.empty() && utf8.front() == ':') // Grip width.
                         {
                             utf8.remove_prefix(1);
                             if (auto g = utf::to_int(utf8))
                             {
                                 w = std::abs(g.value());
-                                utf::trim_front(utf8, ' ');
+                                utf::trim_front(utf8, netxs::whitespaces);
                             }
                         }
                     }
@@ -832,15 +832,15 @@ namespace netxs::app::tile
                 auto slot1 = node->attach(slot::_1, parse_data(parse_data, utf8, ui::fork::min_ratio, grip_bindings_ptr));
                 auto slot2 = node->attach(slot::_2, parse_data(parse_data, utf8, ui::fork::max_ratio, grip_bindings_ptr));
                 slot_ptr->attach(node);
-                utf::trim_front(utf8, ") ");
+                utf::trim_front(utf8, netxs::whitespaces_and<')'>);
             }
             else  // Add application.
             {
-                utf::trim_front(utf8, ' ');
-                auto menuid = utf::take_front(utf8, " ,)").str();
+                utf::trim_front(utf8, netxs::whitespaces);
+                auto menuid = utf::take_front(utf8, netxs::whitespaces_and<',', ')'>).str();
                 if (menuid.empty()) return slot_ptr;
 
-                utf::trim_front(utf8, " ,");
+                utf::trim_front(utf8, netxs::whitespaces_and<','>);
                 if (utf8.size() && utf8.front() == ')') utf8.remove_prefix(1); // pop ')';
 
                 auto& s = *slot_ptr;

src/netxs/desktopio/ansivt.hpp

@@ -137,25 +137,27 @@ namespace netxs::ansi
     static const auto c0_us  = '\x1F'; // Unit Separator.
     static const auto c0_del = '\x7F'; // Delete cell backward.
 
-    static const auto osc_label_title  = "0"   ; // Set icon label and title.
-    static const auto osc_label        = "1"   ; // Set icon label.
-    static const auto osc_title        = "2"   ; // Set title.
-    static const auto osc_xprop        = "3"   ; // Set xprop.
-    static const auto osc_set_palette  = "4"   ; // Set 256 colors palette.
-    static const auto osc_linux_color  = "P"   ; // Set 16 colors palette. (Linux console)
-    static const auto osc_linux_reset  = "R"   ; // Reset 16/256 colors palette. (Linux console)
-    static const auto osc_clipboard    = "52"  ; // Set clipboard.
-    static const auto osc_term_notify  = "9"   ; // Terminal notifications.
-    static const auto osc_set_fgcolor  = "10"  ; // Set fg color.
-    static const auto osc_set_bgcolor  = "11"  ; // Set bg color.
-    static const auto osc_caret_color  = "12"  ; // Set cursor color.
-    static const auto osc_reset_color  = "104" ; // Reset color N to default palette. Without params all palette reset.
-    static const auto osc_reset_fgclr  = "110" ; // Reset fg color to default.
-    static const auto osc_reset_bgclr  = "111" ; // Reset bg color to default.
-    static const auto osc_reset_crclr  = "112" ; // Reset cursor color to default.
-    static const auto osc_semantic_fx  = "133" ; // Semantic markers (shell integration).
-    static const auto osc_title_report = "l"   ; // Get terminal window title.
-    static const auto osc_label_report = "L"   ; // Get terminal window icon label.
+    static const auto osc_label_title  = "0"      ; // Set icon label and title.
+    static const auto osc_label        = "1"      ; // Set icon label.
+    static const auto osc_title        = "2"      ; // Set title.
+    static const auto osc_xprop        = "3"      ; // Set xprop.
+    static const auto osc_set_palette  = "4"      ; // Set 256 colors palette.
+    static const auto osc_linux_color  = "P"      ; // Set 16 colors palette. (Linux console)
+    static const auto osc_linux_reset  = "R"      ; // Reset 16/256 colors palette. (Linux console)
+    static const auto osc_clipboard    = "52"     ; // Set clipboard.
+    static const auto osc_term_notify  = "9"      ; // Terminal notifications.
+    static const auto osc_set_fgcolor  = "10"     ; // Set fg color.
+    static const auto osc_set_bgcolor  = "11"     ; // Set bg color.
+    static const auto osc_caret_color  = "12"     ; // Set cursor color.
+    static const auto osc_reset_color  = "104"    ; // Reset color N to default palette. Without params all palette reset.
+    static const auto osc_reset_fgclr  = "110"    ; // Reset fg color to default.
+    static const auto osc_reset_bgclr  = "111"    ; // Reset bg color to default.
+    static const auto osc_reset_crclr  = "112"    ; // Reset cursor color to default.
+    static const auto osc_semantic_fx  = "133"    ; // Semantic markers (shell integration).
+    static const auto osc_title_report = "l"      ; // Get terminal window title.
+    static const auto osc_label_report = "L"      ; // Get terminal window icon label.
+    static const auto osc_glyph        = "glyph"  ; // Dynamic Glyph Redefinition.
+    static const auto osc_app          = "app"    ; // AnyPlex Protocol.
 
     static const auto sgr_rst       = 0;
     static const auto sgr_sav       = 10;

src/netxs/desktopio/application.hpp

@@ -22,7 +22,7 @@ namespace netxs::app
 
 namespace netxs::app::shared
 {
-    static const auto version = "v2026.03.27";
+    static const auto version = "v2026.04.09";
     static const auto repository = "https://github.com/directvt/vtm";
     static const auto usr_config = "~/.config/vtm/settings.xml"s;
     static const auto sys_config = "/etc/vtm/settings.xml"s;