ultravisor 1.0.3 → 1.0.8

package/webinterface/source/Ultravisor-TimingUtils.js

@@ -0,0 +1,99 @@
+/**
+ * Ultravisor Timing Utilities
+ *
+ * Shared constants and helper functions for timing visualization,
+ * used by both TimingView and ManifestList views.
+ */
+
+// ── Category color palette for timing bar charts ──────────────────────
+const CategoryColors =
+{
+	'Core': { bar: 'linear-gradient(90deg, #5c6bc0, #7986cb)', text: '#9fa8da' },
+	'File I/O': { bar: 'linear-gradient(90deg, #00897b, #26a69a)', text: '#80cbc4' },
+	'Control': { bar: 'linear-gradient(90deg, #f9a825, #fdd835)', text: '#fff59d' },
+	'REST': { bar: 'linear-gradient(90deg, #e65100, #ff6d00)', text: '#ffab91' },
+	'Meadow': { bar: 'linear-gradient(90deg, #6a1b9a, #8e24aa)', text: '#ce93d8' },
+	'Pipeline': { bar: 'linear-gradient(90deg, #00838f, #0097a7)', text: '#80deea' },
+	'Data': { bar: 'linear-gradient(90deg, #4e342e, #6d4c41)', text: '#bcaaa4' },
+	'Interaction': { bar: 'linear-gradient(90deg, #1565c0, #1e88e5)', text: '#90caf9' },
+	'Uncategorized': { bar: 'linear-gradient(90deg, #37474f, #546e7a)', text: '#90a4ae' }
+};
+
+/**
+ * Format milliseconds into a human-readable duration string.
+ *
+ * @param {number} pMs - Duration in milliseconds
+ * @returns {string} Formatted duration (e.g. "42ms", "3s 210ms", "2m 15s")
+ */
+function formatMs(pMs)
+{
+	if (typeof pMs !== 'number' || pMs <= 0)
+	{
+		return '0ms';
+	}
+	if (pMs < 1000)
+	{
+		return Math.round(pMs) + 'ms';
+	}
+	if (pMs < 60000)
+	{
+		let tmpSeconds = Math.floor(pMs / 1000);
+		let tmpMs = Math.round(pMs % 1000);
+		return tmpSeconds + 's ' + tmpMs + 'ms';
+	}
+	let tmpMinutes = Math.floor(pMs / 60000);
+	let tmpSeconds = Math.floor((pMs % 60000) / 1000);
+	return tmpMinutes + 'm ' + tmpSeconds + 's';
+}
+
+/**
+ * Compute total ElapsedMs for a TaskManifest entry by summing its Executions.
+ *
+ * @param {object} pTaskManifest - A task manifest entry with Executions array
+ * @returns {number} Total elapsed time in milliseconds
+ */
+function computeTaskElapsedMs(pTaskManifest)
+{
+	let tmpTotal = 0;
+
+	if (pTaskManifest.Executions && pTaskManifest.Executions.length > 0)
+	{
+		for (let i = 0; i < pTaskManifest.Executions.length; i++)
+		{
+			tmpTotal += (pTaskManifest.Executions[i].ElapsedMs || 0);
+		}
+	}
+
+	return tmpTotal;
+}
+
+/**
+ * Determine the overall status for a task from its Executions array.
+ *
+ * @param {object} pTaskManifest - A task manifest entry with Executions array
+ * @returns {string} Status string (e.g. "Complete", "Error", "Running", "Unknown")
+ */
+function computeTaskStatus(pTaskManifest)
+{
+	if (!pTaskManifest.Executions || pTaskManifest.Executions.length === 0)
+	{
+		return 'Unknown';
+	}
+
+	let tmpLastExec = pTaskManifest.Executions[pTaskManifest.Executions.length - 1];
+	return tmpLastExec.Status || 'Unknown';
+}
+
+/**
+ * Escape HTML special characters for safe insertion into markup.
+ *
+ * @param {*} pValue - Value to escape
+ * @returns {string} Escaped string
+ */
+function escapeHTML(pValue)
+{
+	if (!pValue) return '';
+	return String(pValue).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+module.exports = { CategoryColors, formatMs, computeTaskElapsedMs, computeTaskStatus, escapeHTML };

package/webinterface/source/card-help-content.js

@@ -0,0 +1,46 @@
+// Auto-generated by scripts/generate-card-help.js — do not edit manually.
+// Source markdown files are in docs/card-help/
+module.exports = {
+	"beacon-dispatch": "<h1>Beacon Dispatch</h1><p>Dispatches a work item to a remote Beacon worker node. The task pauses until the Beacon completes execution and reports results back.</p><h2>Settings</h2><ul><li><b>RemoteCapability</b> — Required capability on the Beacon (e.g. <code>Shell</code>, <code>FileSystem</code>, <code>LLM</code>).</li><li><b>RemoteAction</b> — Specific action within the capability (e.g. <code>Execute</code>, <code>Read</code>).</li><li><b>Command</b> — Shell command to execute on the Beacon (when using Shell capability).</li><li><b>Parameters</b> — Command-line parameters for the shell command.</li><li><b>AffinityKey</b> — Worker affinity routing key. Requests with the same key are routed to the same Beacon.</li><li><b>TimeoutMs</b> — Work item timeout in milliseconds (default <code>300000</code>).</li><li><b>InputData</b> — JSON data to pass to the Beacon worker.</li><li><b>Destination</b> — State address to write results to on completion.</li></ul><h2>Outputs</h2><ul><li><b>StdOut</b> — Standard output from the Beacon execution.</li><li><b>Result</b> — Result data from the Beacon.</li><li><b>ExitCode</b> — Exit code of the remote command.</li><li><b>BeaconID</b> — ID of the Beacon that executed the work.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires when the Beacon finishes.</li><li><b>Error</b> — Fires on failure or timeout.</li></ul><h2>Tips</h2><p>Beacon Dispatch is the low-level card for sending arbitrary work to remote workers. Use AffinityKey to ensure related work items run on the same Beacon instance. For common patterns, prefer the specialized cards (LLM Chat Completion, Content Read File, etc.) which use Beacon Dispatch internally with appropriate defaults.</p>",
+	"command": "<h1>Command</h1><p>Executes a shell command on the server and captures its output.</p><h2>Settings</h2><ul><li><b>Command</b> — The shell command to execute (e.g. <code>ls</code>, <code>git</code>, <code>python3</code>).</li><li><b>Parameters</b> — Command-line arguments as a single string.</li><li><b>Description</b> — Human-readable description of what this command does (for documentation only).</li><li><b>WorkingDirectory</b> — Working directory for the command.</li><li><b>TimeoutMs</b> — Command timeout in milliseconds (default <code>300000</code> — 5 minutes).</li><li><b>Environment</b> — JSON object of environment variables to set for the command.</li></ul><h2>Outputs</h2><ul><li><b>StdOut</b> — Standard output from the command.</li><li><b>StdErr</b> — Standard error output from the command.</li><li><b>ExitCode</b> — Exit code (0 typically indicates success).</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires when the command finishes.</li><li><b>Error</b> — Fires if the command fails to start or times out.</li></ul><h2>Tips</h2><p>Use an <b>If Conditional</b> on ExitCode to handle success vs failure. Both Command and Parameters support Pict template expressions, so you can build dynamic commands from state values. Set Environment to inject secrets or configuration without hardcoding them.</p>",
+	"comprehension-intersect": "<h1>Comprehension Intersect</h1><p>Intersects two arrays by matching records on a common field, similar to an SQL inner join.</p><h2>Settings</h2><ul><li><b>SourceAddressA</b> — State address of the first array.</li><li><b>SourceAddressB</b> — State address of the second array.</li><li><b>MatchField</b> — Field name to match records on. Records from both arrays with the same value in this field are merged.</li><li><b>Destination</b> — State address to store the intersected results.</li><li><b>JoinType</b> — Join type (default <code>inner</code>). Inner join returns only records that match in both arrays.</li></ul><h2>Outputs</h2><ul><li><b>Result</b> — Array of merged record objects.</li><li><b>MatchCount</b> — Number of matched records.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after intersection.</li></ul><h2>Tips</h2><p>Use Comprehension Intersect to combine data from two different sources — for example, joining a list of user IDs from one API with user details from another. The matched records are merged into single objects containing fields from both sources.</p>",
+	"content-create-folder": "<h1>Content Create Folder</h1><p>Creates a folder in the content directory on a remote Content System beacon.</p><h2>Settings</h2><ul><li><b>Path</b> — Relative folder path to create.</li><li><b>AffinityKey</b> — Worker affinity key to route to a specific beacon.</li><li><b>TimeoutMs</b> — Timeout in milliseconds (default <code>300000</code>).</li></ul><h2>Outputs</h2><ul><li><b>StdOut</b> — Status message from the beacon.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after the folder is created.</li><li><b>Error</b> — Fires on failure.</li></ul><h2>Tips</h2><p>Use Content Create Folder before <b>Content Save File</b> to ensure the target directory structure exists. The operation is idempotent — creating a folder that already exists succeeds without error.</p>",
+	"content-list-files": "<h1>Content List Files</h1><p>Lists files in a directory on a remote Content System beacon.</p><h2>Settings</h2><ul><li><b>Path</b> — Relative directory path within the content directory. Leave empty for the root.</li><li><b>Pattern</b> — Glob pattern filter (e.g. <code><i>.md</code>, <code></i>.json</code>).</li><li><b>Recursive</b> — When <code>true</code>, lists files in subdirectories.</li><li><b>AffinityKey</b> — Worker affinity key to route to a specific beacon.</li><li><b>TimeoutMs</b> — Timeout in milliseconds (default <code>300000</code>).</li></ul><h2>Outputs</h2><ul><li><b>Files</b> — JSON array of file entries.</li><li><b>StdOut</b> — Status message from the beacon.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after listing.</li><li><b>Error</b> — Fires on failure.</li></ul><h2>Tips</h2><p>Use Content List Files to discover available content on a beacon before processing. Combine with <b>Split Execute</b> to iterate over the file list and read or transform each file.</p>",
+	"content-read-file": "<h1>Content Read File</h1><p>Reads a markdown or content file from a remote Content System beacon.</p><h2>Settings</h2><ul><li><b>FilePath</b> — Relative path within the content directory on the beacon.</li><li><b>Destination</b> — State address to store the file content.</li><li><b>AffinityKey</b> — Worker affinity key to route to a specific beacon.</li><li><b>TimeoutMs</b> — Timeout in milliseconds (default <code>300000</code>).</li></ul><h2>Outputs</h2><ul><li><b>Content</b> — The file content as a string.</li><li><b>StdOut</b> — Status message from the beacon.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after a successful read.</li><li><b>Error</b> — Fires if the file is not found or the beacon is unreachable.</li></ul><h2>Tips</h2><p>Content System cards operate on remote Beacon workers, not the local file system. Use AffinityKey to ensure reads and writes go to the same beacon instance. For local file operations, use <b>Read File</b> instead.</p>",
+	"content-save-file": "<h1>Content Save File</h1><p>Saves content to a file on a remote Content System beacon.</p><h2>Settings</h2><ul><li><b>FilePath</b> — Relative path within the content directory.</li><li><b>Content</b> — The file content to write. Supports Pict template expressions.</li><li><b>AffinityKey</b> — Worker affinity key to route to a specific beacon.</li><li><b>TimeoutMs</b> — Timeout in milliseconds (default <code>300000</code>).</li></ul><h2>Outputs</h2><ul><li><b>FilePath</b> — Path of the saved file.</li><li><b>StdOut</b> — Status message from the beacon.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after a successful save.</li><li><b>Error</b> — Fires on failure.</li></ul><h2>Tips</h2><p>Use Content Save File to publish generated content (reports, processed data, rendered templates) to a Content System. Pair with <b>Content Read File</b> to read-modify-write content files on a beacon.</p>",
+	"copy-file": "<h1>Copy File</h1><p>Copies a file from a source path to a target path.</p><h2>Settings</h2><ul><li><b>Source</b> — Source file path.</li><li><b>TargetFile</b> — Destination file path.</li><li><b>Overwrite</b> — Allow overwriting an existing target file (default <code>true</code>).</li></ul><h2>Outputs</h2><ul><li><b>FileLocation</b> — The target path as specified.</li><li><b>FileName</b> — The target file name only.</li><li><b>FilePath</b> — The fully resolved absolute target path.</li><li><b>BytesCopied</b> — Size of the copied file in bytes.</li></ul><h2>Events</h2><ul><li><b>Done</b> — Fires on successful copy.</li><li><b>Error</b> — Fires if the source is missing or the target cannot be written.</li></ul><h2>Tips</h2><p>Set Overwrite to <code>false</code> to protect existing files from accidental replacement. Both Source and TargetFile support Pict template expressions for dynamic paths.</p>",
+	"csv-transform": "<h1>CSV Transform</h1><p>Transforms an array of parsed CSV records by applying field mappings, filters, and output field selection.</p><h2>Settings</h2><ul><li><b>SourceAddress</b> — State address of the records array to transform.</li><li><b>Destination</b> — State address to store the transformed records.</li><li><b>Delimiter</b> — Delimiter for re-serialization (default <code>,</code>).</li><li><b>FieldMapping</b> — JSON array of mapping objects with <code>From</code>, <code>To</code>, and optional <code>Template</code> properties for field renaming and transformation.</li><li><b>FilterExpression</b> — An expression to filter rows. Only rows where the expression evaluates to true are included.</li><li><b>OutputFields</b> — JSON array of field names to include in the output. Omit to include all fields.</li></ul><h2>Outputs</h2><ul><li><b>Records</b> — The transformed records array.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after transformation.</li></ul><h2>Tips</h2><p>Use FieldMapping to rename columns, compute derived fields with templates, or restructure data. Combine with FilterExpression to extract subsets of records in a single step.</p>",
+	"end": "<h1>End</h1><p>Termination point for the workflow. When execution reaches the End card, the operation completes.</p><h2>Events</h2><ul><li><b>In</b> — Receives the final event from the flow. Accepts up to 5 incoming connections.</li></ul><h2>Tips</h2><p>A flow can have multiple End cards to handle different completion paths (e.g. success vs error). The End card signals that execution is complete and the operation's results are ready. Place End cards at the right side of your flow diagram.</p>",
+	"error-message": "<h1>Error Message</h1><p>Logs an error, warning, info, or debug message to the execution log. Use this card to emit diagnostic information during flow execution without halting the workflow.</p><h2>Settings</h2><ul><li><b>MessageTemplate</b> — The message text to log. Supports Pict template expressions for including state values (default: \"An error occurred.\").</li><li><b>Level</b> — Log level: <code>error</code>, <code>warning</code>, <code>info</code>, or <code>debug</code> (default <code>error</code>).</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after the message is logged. Execution continues normally.</li></ul><h2>Tips</h2><p>Error Message does not stop the flow — it only records a log entry. Place it on error branches to capture diagnostic context when failures occur. Use the <code>info</code> level for progress markers and <code>debug</code> for development-time tracing.</p>",
+	"expression-solver": "<h1>Expression Solver</h1><p>Evaluates a mathematical or logical expression using the Fable ExpressionParser and stores the result in state.</p><h2>Settings</h2><ul><li><b>Expression</b> — The expression to evaluate. Can reference state values by address.</li><li><b>Destination</b> — State address to store the evaluation result.</li></ul><h2>Outputs</h2><ul><li><b>Result</b> — The computed result as a string.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after evaluation.</li><li><b>Error</b> — Fires on parse or evaluation failure.</li></ul><h2>Tips</h2><p>Use Expression Solver for arithmetic calculations, string length checks, or combining multiple state values into a computed result. The expression language supports standard math operators, comparisons, and common functions.</p>",
+	"get-json": "<h1>Get JSON</h1><p>Performs an HTTP GET request and parses the response body as JSON.</p><h2>Settings</h2><ul><li><b>URL</b> — The URL to request. Supports Pict template expressions for dynamic URLs.</li><li><b>Headers</b> — JSON string of additional request headers (e.g. <code>{\"Authorization\": \"Bearer ...\"}</code>).</li><li><b>Destination</b> — State address to store the parsed response data.</li><li><b>TimeoutMs</b> — Request timeout in milliseconds (default <code>30000</code>).</li></ul><h2>Outputs</h2><ul><li><b>Data</b> — The parsed JSON response object.</li><li><b>StatusCode</b> — HTTP response status code.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires on a successful response.</li><li><b>Error</b> — Fires on network failure, timeout, or non-2xx status.</li></ul><h2>Tips</h2><p>For APIs requiring authentication, use <b>Set Values</b> to build the Headers JSON from stored credentials before connecting to the Headers setting input. Use the StatusCode output with an <b>If Conditional</b> to handle different HTTP response codes.</p>",
+	"get-text": "<h1>Get Text</h1><p>Performs an HTTP GET request and returns the response body as plain text.</p><h2>Settings</h2><ul><li><b>URL</b> — The URL to request.</li><li><b>Destination</b> — State address to store the response text.</li><li><b>Headers</b> — JSON string of additional request headers.</li><li><b>TimeoutMs</b> — Request timeout in milliseconds (default <code>30000</code>).</li></ul><h2>Outputs</h2><ul><li><b>Data</b> — The response body as a string.</li><li><b>StatusCode</b> — HTTP response status code.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires on a successful response.</li><li><b>Error</b> — Fires on network failure or timeout.</li></ul><h2>Tips</h2><p>Use Get Text for non-JSON responses: HTML pages, CSV downloads, plain text APIs, or XML feeds. Pipe the output into <b>Parse CSV</b> for CSV data or <b>Replace String</b> for text processing.</p>",
+	"histogram": "<h1>Histogram</h1><p>Computes a frequency distribution over a specific field in a dataset array.</p><h2>Settings</h2><ul><li><b>SourceAddress</b> — State address of the data array to analyze.</li><li><b>Field</b> — Field name to compute frequencies for (default <code>score</code>).</li><li><b>Bins</b> — Number of bins for numeric data (default <code>5</code>).</li><li><b>Destination</b> — State address to store the statistics object.</li><li><b>SortBy</b> — Sort frequency results by <code>count</code> or <code>key</code>.</li></ul><h2>Outputs</h2><ul><li><b>Stats</b> — An object containing the frequency distribution, bin boundaries, and summary statistics.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after computation.</li></ul><h2>Tips</h2><p>Use Histogram after parsing or loading a dataset to get a quick statistical overview. Combine with <b>Template String</b> to generate a text-based report of the distribution.</p>",
+	"if-conditional": "<h1>If Conditional</h1><p>Evaluates a condition and branches execution to the True or False output. This is the primary decision-making card in a flow.</p><h2>Settings</h2><ul><li><b>DataAddress</b> — State address of the value to test.</li><li><b>CompareValue</b> — Value to compare against.</li><li><b>Operator</b> — Comparison operator: <code>==</code>, <code>!=</code>, <code>></code>, <code><</code>, <code>>=</code>, <code><=</code>, <code>contains</code>, <code>startsWith</code>, <code>endsWith</code>. Default <code>==</code>.</li><li><b>Expression</b> — A full expression string. When set, DataAddress/CompareValue/Operator are ignored and the expression is evaluated directly.</li></ul><h2>Outputs</h2><ul><li><b>Result</b> — Boolean result of the evaluation.</li></ul><h2>Events</h2><ul><li><b>True</b> — Fires when the condition is true.</li><li><b>False</b> — Fires when the condition is false.</li></ul><h2>Tips</h2><p>Use Expression for complex conditions that combine multiple state values. For simple equality checks, DataAddress + CompareValue + Operator is more readable. The False output is positioned at the bottom of the card for visual clarity in flow diagrams.</p>",
+	"launch-operation": "<h1>Launch Operation</h1><p>Executes a child operation by its hash, with isolated operation state. This enables modular flow composition by calling one operation from within another.</p><h2>Settings</h2><ul><li><b>OperationHash</b> — The hash identifier of the operation to launch.</li><li><b>InputData</b> — JSON data to pass as input to the child operation.</li><li><b>TimeoutMs</b> — Maximum execution time in milliseconds. Set to <code>0</code> for unlimited.</li><li><b>InheritGlobalState</b> — When <code>true</code> (default), copies the parent's GlobalState into the child operation.</li></ul><h2>Outputs</h2><ul><li><b>Result</b> — The result data returned by the child operation.</li><li><b>Status</b> — Final status of the child operation.</li><li><b>ElapsedMs</b> — Execution time of the child operation in milliseconds.</li></ul><h2>Events</h2><ul><li><b>Completed</b> — Fires when the child operation finishes.</li><li><b>Error</b> — Fires if the child operation fails or times out.</li></ul><h2>Tips</h2><p>Use Launch Operation to break complex workflows into reusable sub-operations. The child operation runs with its own isolated state, so it cannot accidentally modify the parent's local state. Use InheritGlobalState to share configuration and credentials.</p>",
+	"list-files": "<h1>List Files</h1><p>Lists files in a directory with optional glob pattern filtering.</p><h2>Settings</h2><ul><li><b>Folder</b> — Directory path to list.</li><li><b>Pattern</b> — Glob pattern filter (e.g. <code><i>.txt</code>, <code></i>.json</code>). Default <code>*</code> matches all files.</li><li><b>Destination</b> — State address to store the resulting file list.</li><li><b>Recursive</b> — When <code>true</code>, includes files in subdirectories.</li><li><b>IncludeDirectories</b> — When <code>true</code>, includes directory entries in the results.</li></ul><h2>Outputs</h2><ul><li><b>Files</b> — Array of file name strings matching the pattern.</li><li><b>FileCount</b> — Number of entries found.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after listing is complete.</li><li><b>Error</b> — Fires if the directory cannot be read.</li></ul><h2>Tips</h2><p>Use with <b>Split Execute</b> to iterate over the file list and process each file individually. Combine Recursive mode with a specific Pattern to find files deep in a directory tree.</p>",
+	"llm-chat-completion": "<h1>LLM Chat Completion</h1><p>Sends messages to a large language model and returns the completion. Supports multi-turn conversation history with persistence across operation runs.</p><h2>Settings</h2><ul><li><b>SystemPrompt</b> — System prompt text that sets the LLM's behavior and context.</li><li><b>UserPrompt</b> — User prompt text for the current turn.</li><li><b>Messages</b> — JSON array of message objects <code>[{role, content}]</code> for direct control over the conversation. Overrides SystemPrompt/UserPrompt when set.</li><li><b>Model</b> — Override the default model name.</li><li><b>Temperature</b> — Sampling temperature (0–2). Lower values are more deterministic.</li><li><b>MaxTokens</b> — Maximum tokens to generate (default <code>4096</code>).</li><li><b>TopP</b> — Nucleus sampling parameter.</li><li><b>StopSequences</b> — JSON array of sequences that stop generation.</li><li><b>ResponseFormat</b> — Set to <code>json_object</code> to force JSON output.</li><li><b>InputAddress</b> — State address to read additional context data from (appended to UserPrompt).</li><li><b>Destination</b> — State address to write the completion text to.</li></ul><h2>Conversation History</h2><ul><li><b>ConversationAddress</b> — State address to store message history for multi-turn conversations.</li><li><b>AppendToConversation</b> — Append this exchange to history (default <code>true</code> when ConversationAddress is set).</li><li><b>ConversationMaxMessages</b> — Sliding window: maximum non-system messages to keep.</li><li><b>ConversationMaxTokens</b> — Token budget for history (approximate, trims oldest messages).</li><li><b>PersistConversation</b> — Copy conversation history to GlobalState for cross-operation persistence.</li><li><b>ConversationPersistAddress</b> — GlobalState address for persistence.</li></ul><h2>Dispatch</h2><ul><li><b>AffinityKey</b> — Route to a specific Beacon worker for consistent model access.</li><li><b>TimeoutMs</b> — Timeout in milliseconds (default <code>120000</code>).</li></ul><h2>Outputs</h2><ul><li><b>Content</b> — The LLM's response text.</li><li><b>Model</b> — Model that generated the response.</li><li><b>PromptTokens</b> / <b>CompletionTokens</b> / <b>TotalTokens</b> — Token usage statistics.</li><li><b>FinishReason</b> — Why the completion ended (<code>stop</code>, <code>length</code>, etc.).</li><li><b>BeaconID</b> — ID of the Beacon worker that executed the request.</li></ul><h2>Tips</h2><p>Use ConversationAddress with PersistConversation to build chatbots that maintain context across multiple operation runs. Set ResponseFormat to <code>json_object</code> when you need structured output that downstream cards can parse. Use Temperature <code>0</code> for deterministic, reproducible results.</p>",
+	"llm-embedding": "<h1>LLM Embedding</h1><p>Generates vector embeddings for text input using an LLM provider. Dispatches the work to a Beacon with LLM capability.</p><h2>Settings</h2><ul><li><b>Text</b> — The text to embed. Supports Pict template expressions.</li><li><b>Model</b> — Override the default embedding model.</li><li><b>Dimensions</b> — Requested embedding dimensions (model-dependent).</li><li><b>InputAddress</b> — State address to read text from (alternative to Text setting).</li><li><b>Destination</b> — State address to write the embedding vector to.</li><li><b>AffinityKey</b> — Route to a specific Beacon worker.</li><li><b>TimeoutMs</b> — Timeout in milliseconds (default <code>60000</code>).</li></ul><h2>Outputs</h2><ul><li><b>Embedding</b> — JSON array of floating-point numbers representing the embedding vector.</li><li><b>Dimensions</b> — Number of dimensions in the embedding.</li><li><b>Model</b> — Model used for embedding.</li><li><b>BeaconID</b> — ID of the Beacon that executed the work.</li></ul><h2>Tips</h2><p>Use embeddings for semantic search, clustering, or similarity comparisons. Store embeddings in a database via <b>Meadow Create</b> for later retrieval. Combine with <b>Expression Solver</b> or downstream processing to compute cosine similarity between vectors.</p>",
+	"llm-tool-use": "<h1>LLM Tool Use</h1><p>Sends messages to a large language model with tool (function) definitions, enabling the LLM to request tool calls that your flow can execute.</p><h2>Settings</h2><ul><li><b>SystemPrompt</b> — System prompt text.</li><li><b>UserPrompt</b> — User prompt text.</li><li><b>Messages</b> — JSON array of messages for direct conversation control.</li><li><b>Tools</b> — JSON array of tool definitions describing available functions the LLM can call.</li><li><b>Model</b> — Override model name.</li><li><b>ToolChoice</b> — <code>auto</code> (LLM decides), <code>none</code> (no tools), or a specific tool name (default <code>auto</code>).</li><li><b>Temperature</b> — Sampling temperature.</li><li><b>MaxTokens</b> — Maximum tokens to generate.</li><li><b>ConversationAddress</b> — State address for multi-turn history.</li><li><b>AppendToConversation</b> — Append this exchange to history.</li><li><b>InputAddress</b> — State address to read context data from.</li><li><b>Destination</b> — State address to write completion content.</li><li><b>AffinityKey</b> — Route to a specific Beacon worker.</li><li><b>TimeoutMs</b> — Timeout in milliseconds (default <code>120000</code>).</li></ul><h2>Outputs</h2><ul><li><b>Content</b> — The LLM's text response (may be empty if tool calls were made).</li><li><b>ToolCalls</b> — JSON array of tool call objects with function names and arguments.</li><li><b>Model</b> — Model that generated the response.</li><li><b>FinishReason</b> — <code>stop</code> for normal completion, <code>tool_calls</code> when tools were invoked.</li><li><b>PromptTokens</b> / <b>CompletionTokens</b> — Token usage.</li><li><b>BeaconID</b> — Beacon worker ID.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires when the LLM responds.</li><li><b>ToolCall</b> — Fires when the LLM requests a tool call.</li><li><b>Error</b> — Fires on failure.</li></ul><h2>Tips</h2><p>Use the ToolCall event to route tool invocations to the appropriate processing cards, then feed results back for another LLM turn. This enables agent-style workflows where the LLM can gather information and take actions through your defined tools.</p>",
+	"meadow-count": "<h1>Meadow Count</h1><p>Counts records for an entity via a Meadow REST API endpoint, with optional filtering.</p><h2>Settings</h2><ul><li><b>Entity</b> — Entity (table) name.</li><li><b>Endpoint</b> — Base URL of the Meadow API server.</li><li><b>Destination</b> — State address to store the count value.</li><li><b>Headers</b> — JSON string of request headers for authentication.</li><li><b>Filter</b> — Meadow filter expression to count only matching records.</li></ul><h2>Outputs</h2><ul><li><b>Count</b> — Number of records matching the criteria.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after the count is retrieved.</li><li><b>Error</b> — Fires on failure.</li></ul><h2>Tips</h2><p>Use Meadow Count before <b>Meadow Reads</b> to check the result set size, or to report progress statistics. It is much faster than reading all records when you only need the total.</p>",
+	"meadow-create": "<h1>Meadow Create</h1><p>Creates a new record via a Meadow REST API endpoint.</p><h2>Settings</h2><ul><li><b>Entity</b> — Entity (table) name.</li><li><b>Endpoint</b> — Base URL of the Meadow API server.</li><li><b>DataAddress</b> — State address of the object containing the record data to create.</li><li><b>Headers</b> — JSON string of request headers for authentication.</li><li><b>Destination</b> — State address to store the created record (includes server-generated fields like ID).</li></ul><h2>Outputs</h2><ul><li><b>Created</b> — The newly created record object with its assigned ID.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after the record is created.</li><li><b>Error</b> — Fires on failure.</li></ul><h2>Tips</h2><p>Build the record data with <b>Set Values</b> or <b>Template String</b> before passing it to Meadow Create. The created record output includes the server-assigned ID, which you can use in subsequent steps.</p>",
+	"meadow-delete": "<h1>Meadow Delete</h1><p>Deletes a record by its ID via a Meadow REST API endpoint.</p><h2>Settings</h2><ul><li><b>Entity</b> — Entity (table) name.</li><li><b>Endpoint</b> — Base URL of the Meadow API server.</li><li><b>RecordID</b> — The ID of the record to delete.</li><li><b>Headers</b> — JSON string of request headers for authentication.</li></ul><h2>Events</h2><ul><li><b>Done</b> — Fires after the record is deleted.</li><li><b>Error</b> — Fires on failure.</li></ul><h2>Tips</h2><p>Meadow Delete is permanent — consider adding a <b>Value Input</b> confirmation step before deleting records in user-facing workflows. Build the RecordID dynamically with template expressions when deleting records identified by earlier processing steps.</p>",
+	"meadow-read": "<h1>Meadow Read</h1><p>Reads a single record by its ID from a Meadow REST API endpoint.</p><h2>Settings</h2><ul><li><b>Entity</b> — Entity (table) name to query.</li><li><b>Endpoint</b> — Base URL of the Meadow API server.</li><li><b>RecordID</b> — The ID of the record to retrieve.</li><li><b>Destination</b> — State address to store the retrieved record.</li><li><b>Headers</b> — JSON string of additional request headers for authentication.</li></ul><h2>Outputs</h2><ul><li><b>Record</b> — The retrieved record object.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after the record is retrieved.</li><li><b>Error</b> — Fires if the record is not found or the request fails.</li></ul><h2>Tips</h2><p>Use <b>Set Values</b> or <b>Template String</b> to build the RecordID dynamically from other state values. Pair with <b>Meadow Update</b> to read-modify-write a record.</p>",
+	"meadow-reads": "<h1>Meadow Reads</h1><p>Reads multiple records from a Meadow REST API endpoint, with optional filtering and pagination.</p><h2>Settings</h2><ul><li><b>Entity</b> — Entity (table) name to query.</li><li><b>Endpoint</b> — Base URL of the Meadow API server.</li><li><b>Filter</b> — Meadow filter expression to narrow the result set (e.g. <code>FBV~IDUser~EQ~42~0~</code>).</li><li><b>Destination</b> — State address to store the records array.</li><li><b>Headers</b> — JSON string of request headers for authentication.</li><li><b>PageSize</b> — Number of records per page (default <code>100</code>).</li><li><b>PageNumber</b> — Zero-based page number (default <code>0</code>).</li></ul><h2>Outputs</h2><ul><li><b>Records</b> — Array of retrieved record objects.</li><li><b>RecordCount</b> — Number of records returned.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after records are retrieved.</li><li><b>Error</b> — Fires on request failure.</li></ul><h2>Tips</h2><p>Use the Meadow filter expression to limit results server-side for better performance. Combine with <b>Split Execute</b> to process each record individually, or with <b>Comprehension Intersect</b> to join data from two entities.</p>",
+	"meadow-update": "<h1>Meadow Update</h1><p>Updates an existing record via a Meadow REST API endpoint.</p><h2>Settings</h2><ul><li><b>Entity</b> — Entity (table) name.</li><li><b>Endpoint</b> — Base URL of the Meadow API server.</li><li><b>DataAddress</b> — State address of the record data to update. Must include the record's ID field.</li><li><b>Headers</b> — JSON string of request headers for authentication.</li><li><b>Destination</b> — State address to store the updated record.</li></ul><h2>Outputs</h2><ul><li><b>Updated</b> — The updated record object.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after the update.</li><li><b>Error</b> — Fires on failure.</li></ul><h2>Tips</h2><p>Use <b>Meadow Read</b> first to load the current record, modify the fields you need with <b>Set Values</b>, then pass the modified object to Meadow Update. The data object must include the record's primary key field.</p>",
+	"parse-csv": "<h1>Parse CSV</h1><p>Parses CSV text into an array of records (objects with field names as keys).</p><h2>Settings</h2><ul><li><b>SourceAddress</b> — State address containing the CSV text to parse.</li><li><b>Delimiter</b> — Column delimiter character (default <code>,</code>).</li><li><b>HasHeaders</b> — When <code>true</code>, the first row provides field names. When <code>false</code>, fields are indexed numerically.</li><li><b>Destination</b> — State address to store the parsed records array.</li><li><b>QuoteCharacter</b> — Character used to quote fields that contain the delimiter (default <code>\"</code>).</li><li><b>TrimFields</b> — Trim leading/trailing whitespace from field values.</li><li><b>SkipEmptyLines</b> — Skip blank lines in the input.</li></ul><h2>Outputs</h2><ul><li><b>Records</b> — Array of parsed row objects.</li><li><b>ColumnCount</b> — Number of columns detected.</li><li><b>Headers</b> — Array of header names from the first row.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after parsing.</li></ul><h2>Tips</h2><p>Chain <b>Read File</b> → <b>Parse CSV</b> → <b>CSV Transform</b> for a complete data import pipeline. Use TrimFields and SkipEmptyLines to handle messy real-world CSV exports cleanly.</p>",
+	"read-file-buffered": "<h1>Read File Buffered</h1><p>Reads a file in chunks up to a maximum buffer size, splitting on a preferred character boundary. Ideal for processing large files that should not be loaded entirely into memory.</p><h2>Settings</h2><ul><li><b>FilePath</b> — Path to the file to read.</li><li><b>Encoding</b> — Character encoding (default <code>utf8</code>).</li><li><b>MaxBufferSize</b> — Maximum bytes per chunk (default <code>65536</code>).</li><li><b>SplitCharacter</b> — Preferred character to split on (default newline). The chunk is trimmed to the last occurrence of this character within the buffer so records are not broken mid-line.</li><li><b>ByteOffset</b> — Byte offset to start reading from. Use <code>0</code> for the first chunk and feed the output ByteOffset back for continuation.</li></ul><h2>Outputs</h2><ul><li><b>FileContent</b> — Content of the current chunk.</li><li><b>BytesRead</b> — Bytes in this chunk.</li><li><b>ByteOffset</b> — Updated byte offset for the next read.</li><li><b>IsComplete</b> — <code>true</code> when the entire file has been read.</li><li><b>FileName</b> — Base name of the file.</li><li><b>TotalFileSize</b> — Total size of the file in bytes.</li></ul><h2>Events</h2><ul><li><b>ReadComplete</b> — Fires when a chunk is read successfully.</li><li><b>Error</b> — Fires on read failure.</li></ul><h2>Tips</h2><p>Wire the ByteOffset output back to the ByteOffset setting input and use an <b>If Conditional</b> on IsComplete to create a read loop. This pattern lets you process files of any size line-by-line or paragraph-by-paragraph.</p>",
+	"read-file": "<h1>Read File</h1><p>Reads a file from the local file system into operation state.</p><h2>Settings</h2><ul><li><b>FilePath</b> — Path to the file to read. Supports Pict template expressions for dynamic paths.</li><li><b>Encoding</b> — Character encoding (default <code>utf8</code>). Use <code>binary</code> for non-text files.</li><li><b>MaxBytes</b> — Maximum bytes to read. Set to <code>0</code> for unlimited.</li></ul><h2>Outputs</h2><ul><li><b>FileContent</b> — The full text content of the file.</li><li><b>BytesRead</b> — Number of bytes that were read.</li><li><b>FileName</b> — The base name of the file (no directory).</li></ul><h2>Events</h2><ul><li><b>ReadComplete</b> — Fires after a successful read.</li><li><b>Error</b> — Fires if the file cannot be found or read.</li></ul><h2>Tips</h2><p>For very large files, use <b>Read File Buffered</b> instead to process content in chunks. Use MaxBytes as a safety limit to avoid loading unexpectedly large files into memory.</p>",
+	"read-json": "<h1>Read JSON</h1><p>Reads a JSON file from disk, parses it, and stores the resulting object in operation state.</p><h2>Settings</h2><ul><li><b>FilePath</b> — Path to the JSON file.</li><li><b>Destination</b> — State address to store the parsed data. If empty, data is stored at the default output address.</li></ul><h2>Outputs</h2><ul><li><b>Data</b> — The parsed JSON object or array.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after successful read and parse.</li><li><b>Error</b> — Fires if the file is missing or contains invalid JSON.</li></ul><h2>Tips</h2><p>Pair with <b>Write JSON</b> to round-trip configuration or intermediate data. Use the Destination setting to place the parsed data at a specific location in your operation state for downstream tasks.</p>",
+	"replace-string": "<h1>Replace String</h1><p>Replaces all occurrences of a search string within the input text.</p><h2>Settings</h2><ul><li><b>InputString</b> — The source text to search within. Supports Pict template expressions.</li><li><b>SearchString</b> — The text or pattern to find.</li><li><b>ReplaceString</b> — The replacement text (empty string to delete matches).</li><li><b>UseRegex</b> — When <code>true</code>, treats SearchString as a regular expression.</li><li><b>CaseSensitive</b> — Case-sensitive matching (default <code>true</code>).</li></ul><h2>Outputs</h2><ul><li><b>ReplacedString</b> — The result after all replacements.</li><li><b>ReplacementCount</b> — Number of replacements made.</li></ul><h2>Events</h2><ul><li><b>ReplaceComplete</b> — Fires after replacement.</li><li><b>Error</b> — Fires on failure (e.g. invalid regex).</li></ul><h2>Tips</h2><p>Enable UseRegex for advanced pattern matching such as removing HTML tags, normalizing whitespace, or extracting structured tokens. Use ReplacementCount to verify that expected substitutions occurred.</p>",
+	"rest-request": "<h1>REST Request</h1><p>Performs a fully configurable HTTP request with support for any method, custom content types, request bodies, retries, and timeout control.</p><h2>Settings</h2><ul><li><b>URL</b> — The URL to request.</li><li><b>Method</b> — HTTP method: <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>DELETE</code>, <code>PATCH</code>, etc. (default <code>GET</code>).</li><li><b>ContentType</b> — Content-Type header value (default <code>application/json</code>).</li><li><b>Headers</b> — JSON string of additional request headers.</li><li><b>Body</b> — Request body as a JSON string or raw text.</li><li><b>Destination</b> — State address to store the response.</li><li><b>Retries</b> — Number of retries on failure (default <code>0</code>).</li><li><b>TimeoutMs</b> — Request timeout in milliseconds (default <code>30000</code>).</li><li><b>RetryDelayMs</b> — Delay between retry attempts in milliseconds (default <code>1000</code>).</li></ul><h2>Outputs</h2><ul><li><b>Response</b> — The response data.</li><li><b>StatusCode</b> — HTTP response status code.</li><li><b>ResponseHeaders</b> — JSON string of response headers.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires on success.</li><li><b>Error</b> — Fires on failure after all retries are exhausted.</li></ul><h2>Tips</h2><p>REST Request is the most flexible HTTP card. Use it for DELETE operations, form-encoded POST bodies, XML APIs, or any case where Get JSON / Send JSON are too restrictive. The Retries setting with RetryDelayMs provides built-in resilience for flaky endpoints.</p>",
+	"send-json": "<h1>Send JSON</h1><p>Sends JSON data to a URL via HTTP POST or PUT.</p><h2>Settings</h2><ul><li><b>URL</b> — The URL to send data to.</li><li><b>Method</b> — HTTP method: <code>POST</code> or <code>PUT</code> (default <code>POST</code>).</li><li><b>DataAddress</b> — State address of the object to send as the request body.</li><li><b>Headers</b> — JSON string of additional request headers.</li><li><b>Destination</b> — State address to store the response data.</li><li><b>TimeoutMs</b> — Request timeout in milliseconds (default <code>30000</code>).</li></ul><h2>Outputs</h2><ul><li><b>Response</b> — The parsed response data.</li><li><b>StatusCode</b> — HTTP response status code.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires on success.</li><li><b>Error</b> — Fires on failure.</li></ul><h2>Tips</h2><p>Use Send JSON for creating or updating resources via REST APIs. For more control over the request (custom Content-Type, DELETE method, retries), use <b>REST Request</b> instead.</p>",
+	"set-values": "<h1>Set Values</h1><p>Sets one or more values in operation state at specified addresses. This is the primary card for initializing variables, copying data between state locations, and injecting literal values.</p><h2>Settings</h2><ul><li><b>Mappings</b> — An array of mapping objects. Each mapping has a <code>To</code> address (where to write) and either a <code>Value</code> (literal) or <code>From</code> address (copy from state).</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after all mappings are applied.</li><li><b>Error</b> — Fires if a mapping fails.</li></ul><h2>Tips</h2><p>Use Set Values at the start of a flow to initialize default values before branching logic. Mappings are applied in order, so later entries can reference values set by earlier ones within the same card.</p>",
+	"split-execute": "<h1>Split Execute</h1><p>Splits a string by a delimiter and processes each token through a sub-graph, acting as a loop iterator within the flow.</p><h2>Settings</h2><ul><li><b>InputString</b> — The string to split. Supports Pict template expressions.</li><li><b>SplitDelimiter</b> — Delimiter to split on (default newline <code>\\n</code>).</li><li><b>SkipEmpty</b> — When <code>true</code>, skips empty tokens after splitting.</li><li><b>TrimTokens</b> — When <code>true</code>, trims whitespace from each token.</li></ul><h2>Outputs</h2><ul><li><b>CurrentToken</b> — The current token being processed.</li><li><b>TokenIndex</b> — Zero-based index of the current token.</li><li><b>TokenCount</b> — Total number of tokens.</li><li><b>CompletedCount</b> — Number of tokens processed so far.</li></ul><h2>Events</h2><ul><li><b>TokenDataSent</b> — Fires for each token, sending it through the sub-graph.</li><li><b>CompletedAllSubtasks</b> — Fires after all tokens have been processed.</li><li><b>Error</b> — Fires on failure.</li></ul><h2>How It Works</h2><ol><li>The input string is split into tokens by the delimiter.</li><li>For each token, <b>TokenDataSent</b> fires with the token data in state.</li><li>Connect the downstream processing graph to TokenDataSent.</li><li>Wire the end of your processing graph back to the <b>StepComplete</b> event input to advance to the next token.</li><li>After all tokens are processed, <b>CompletedAllSubtasks</b> fires.</li></ol><h2>Tips</h2><p>Split Execute is the primary looping mechanism in Ultravisor flows. Use it with <b>List Files</b> output to process each file, or with newline-delimited text to process line-by-line.</p>",
+	"start": "<h1>Start</h1><p>Entry point for the workflow. Every operation flow begins with a Start card.</p><h2>Events</h2><ul><li><b>Out</b> — Fires when the operation begins execution. Connect this to the first processing card in your flow.</li></ul><h2>Tips</h2><p>Each flow should have exactly one Start card. The Start card has no settings — it simply fires its Out event when the operation is triggered. Place it at the left side of your flow diagram for a clean left-to-right layout.</p>",
+	"string-appender": "<h1>String Appender</h1><p>Appends a string to an existing value at a specified state address. Useful for building up output incrementally across loop iterations or multiple steps.</p><h2>Settings</h2><ul><li><b>InputString</b> — The text to append. Supports Pict template expressions.</li><li><b>OutputAddress</b> — State address of the string to append to.</li><li><b>AppendNewline</b> — When <code>true</code>, appends a newline character after the input string.</li><li><b>Separator</b> — String inserted between the existing content and new content. Overrides AppendNewline when set.</li></ul><h2>Outputs</h2><ul><li><b>AppendedString</b> — The full accumulated string after appending.</li></ul><h2>Events</h2><ul><li><b>Completed</b> — Fires after the append.</li></ul><h2>Tips</h2><p>Combine with <b>Split Execute</b> to build a report line by line. Use AppendNewline for log-style output or Separator for CSV-style concatenation with a custom delimiter.</p>",
+	"template-string": "<h1>Template String</h1><p>Processes a Pict template string against the current operation state, resolving expressions like <code>{~D:Record.Name~}</code> into their runtime values.</p><h2>Settings</h2><ul><li><b>Template</b> — A Pict template string containing <code>{~D:...~}</code> expressions that reference state addresses.</li><li><b>Destination</b> — State address to store the rendered result. If empty, the result is available at the default output.</li></ul><h2>Outputs</h2><ul><li><b>Result</b> — The fully rendered template output.</li></ul><h2>Events</h2><ul><li><b>Complete</b> — Fires after rendering.</li><li><b>Error</b> — Fires if template parsing fails.</li></ul><h2>Tips</h2><p>Template String is the workhorse for building dynamic URLs, file paths, messages, and prompts. Any Pict template expression is supported, including conditionals and joins. Chain multiple Template String cards to build complex content from intermediate values.</p>",
+	"value-input": "<h1>Value Input</h1><p>Pauses flow execution and prompts the user for input. The flow resumes when the user provides a value or cancels.</p><h2>Settings</h2><ul><li><b>PromptMessage</b> — The message displayed to the user (default: \"Please provide a value:\").</li><li><b>OutputAddress</b> — State address where the user's input will be stored.</li><li><b>InputType</b> — Type of input control: <code>text</code>, <code>number</code>, <code>boolean</code>, or <code>select</code> (default <code>text</code>).</li><li><b>DefaultValue</b> — Pre-filled default value.</li><li><b>Options</b> — JSON array of allowed values when InputType is <code>select</code>.</li></ul><h2>Outputs</h2><ul><li><b>InputValue</b> — The value provided by the user.</li></ul><h2>Events</h2><ul><li><b>ValueInputComplete</b> — Fires when the user submits a value.</li><li><b>Cancelled</b> — Fires if the user cancels without providing input.</li></ul><h2>Tips</h2><p>Use Value Input for human-in-the-loop workflows: approval gates, manual data entry, or parameter selection at runtime. Wire the Cancelled output to an appropriate fallback path. Use <code>select</code> InputType with Options for constrained choices.</p>",
+	"write-file": "<h1>Write File</h1><p>Writes text content to a file on disk.</p><h2>Settings</h2><ul><li><b>FilePath</b> — Path to the output file. Intermediate directories are created automatically.</li><li><b>Content</b> — The text content to write. Supports Pict template expressions.</li><li><b>Encoding</b> — Character encoding (default <code>utf8</code>).</li><li><b>Append</b> — When <code>true</code>, appends to an existing file instead of overwriting it.</li><li><b>LineEnding</b> — Force a line ending style: <code>lf</code>, <code>crlf</code>, or leave empty for no conversion.</li></ul><h2>Outputs</h2><ul><li><b>FileLocation</b> — The path as specified (may be relative).</li><li><b>FileName</b> — The base file name only.</li><li><b>FilePath</b> — The fully resolved absolute path.</li><li><b>BytesWritten</b> — Number of bytes written.</li></ul><h2>Events</h2><ul><li><b>WriteComplete</b> — Fires on success.</li><li><b>Error</b> — Fires on write failure.</li></ul><h2>Tips</h2><p>Use Append mode with a <b>String Appender</b> to build log files or accumulate output across loop iterations.</p>",
+	"write-json": "<h1>Write JSON</h1><p>Serializes a state object to JSON and writes it to a file on disk.</p><h2>Settings</h2><ul><li><b>FilePath</b> — Path to the output JSON file.</li><li><b>DataAddress</b> — State address of the data to serialize. If empty, uses the full operation state.</li><li><b>PrettyFormat</b> — Pretty-print with indentation (default <code>true</code>).</li><li><b>IndentType</b> — Indent character: <code>tab</code> or <code>space</code> (default <code>tab</code>).</li><li><b>IndentCount</b> — Number of indent characters per level (default <code>1</code>).</li><li><b>SortKeys</b> — Alphabetically sort object keys for deterministic output.</li></ul><h2>Outputs</h2><ul><li><b>FileLocation</b> — The path as specified.</li><li><b>FileName</b> — The base file name only.</li><li><b>FilePath</b> — The fully resolved absolute path.</li><li><b>BytesWritten</b> — Number of bytes written.</li></ul><h2>Events</h2><ul><li><b>Done</b> — Fires on success.</li><li><b>Error</b> — Fires on write failure.</li></ul><h2>Tips</h2><p>Enable SortKeys for config files that will be compared across versions or stored in version control.</p>"
+};

package/webinterface/source/cards/Ultravisor-BuiltIn-CardConfigs.js

@@ -0,0 +1,174 @@
+/**
+ * Built-in card configurations for Ultravisor.
+ *
+ * Task-matched cards are generated at runtime from definitions fetched via the
+ * `/TaskType` API endpoint.  The `generateCardConfigs()` function converts an
+ * array of Definition objects into PictFlowCard constructor options using the
+ * CardConfigGenerator, applies per-card visual overrides, and appends the two
+ * flow-marker cards (Start / End) which have no backend task type.
+ *
+ * Visual overrides and flow-marker configs are the only data defined here;
+ * task definitions live in standalone JSON files consumed by both server and
+ * client.
+ */
+
+const generateCardConfig = require('./Ultravisor-CardConfigGenerator.js');
+
+// Card help content generated from docs/card-help/ markdown files.
+// Falls back to an empty map if the module has not been generated yet.
+let _CardHelpContent = {};
+try
+{
+	_CardHelpContent = require('../card-help-content.js');
+}
+catch (pError)
+{
+	// No card help content available — Help tabs will not appear.
+}
+
+
+// ═══════════════════════════════════════════════════════════════════════
+//  VISUAL OVERRIDES per card hash
+//  These preserve the hand-crafted styling from the original card files.
+// ═══════════════════════════════════════════════════════════════════════
+
+const _CardOverrides =
+{
+	// ── Interaction ─────────────────────────────────────────────
+	'error-message':
+	{
+		Width: 220
+	},
+	'value-input':
+	{
+		// Amber palette instead of default Interaction red
+		TitleBarColor: '#f57f17',
+		BodyStyle: { fill: '#fffde7', stroke: '#f57f17' },
+		Width: 220
+	},
+
+	// ── Control ────────────────────────────────────────────────
+	'if-conditional':
+	{
+		// False branch goes to bottom for visual branching
+		Outputs:
+		[
+			{ Name: 'True', Side: 'right-bottom', PortType: 'event-out' },
+			{ Name: 'False', Side: 'bottom', PortType: 'event-out' },
+			{ Name: 'Result', Side: 'right-top', PortType: 'value' }
+		]
+	},
+	'split-execute':
+	{
+		// Teal palette to distinguish from other Control cards
+		TitleBarColor: '#00695c',
+		BodyStyle: { fill: '#e0f2f1', stroke: '#00695c' },
+		// Custom output positions for the two event paths
+		Outputs:
+		[
+			{ Name: 'TokenDataSent', Side: 'right-bottom', PortType: 'event-out' },
+			{ Name: 'CompletedAllSubtasks', Side: 'right-bottom', PortType: 'event-out' },
+			{ Name: 'Error', Side: 'bottom', PortType: 'error' },
+			{ Name: 'CurrentToken', Side: 'right-top', PortType: 'value' },
+			{ Name: 'TokenIndex', Side: 'right-top', PortType: 'value' },
+			{ Name: 'TokenCount', Side: 'right-top', PortType: 'value' },
+			{ Name: 'CompletedCount', Side: 'right-top', PortType: 'value' }
+		]
+	}
+};
+
+
+// ═══════════════════════════════════════════════════════════════════════
+//  FLOW MARKER CONFIGS (no backend task type)
+// ═══════════════════════════════════════════════════════════════════════
+
+const _FlowMarkerConfigs =
+[
+	// ── Start ──────────────────────────────────────────────────
+	{
+		Title: 'Start',
+		Code: 'start',
+		Description: 'Entry point for the workflow.',
+		Category: 'Flow Control',
+		Capability: 'Flow Control',
+		Action: 'Begin',
+		Tier: 'Engine',
+		TitleBarColor: '#455a64',
+		BodyStyle: { fill: '#eceff1', stroke: '#455a64' },
+		Width: 140,
+		Height: 80,
+		Inputs: [],
+		Outputs:
+		[
+			{ Name: 'Out', Side: 'right-bottom', PortType: 'event-out' }
+		]
+	},
+	// ── End ────────────────────────────────────────────────────
+	{
+		Title: 'End',
+		Code: 'end',
+		Description: 'Termination point for the workflow.',
+		Category: 'Flow Control',
+		Capability: 'Flow Control',
+		Action: 'End',
+		Tier: 'Engine',
+		TitleBarColor: '#455a64',
+		BodyStyle: { fill: '#eceff1', stroke: '#455a64' },
+		Width: 140,
+		Height: 80,
+		Inputs:
+		[
+			{ Name: 'In', Side: 'left-bottom', PortType: 'event-in', MinimumInputCount: 1, MaximumInputCount: 5 }
+		],
+		Outputs: []
+	}
+];
+
+
+// ═══════════════════════════════════════════════════════════════════════
+//  PUBLIC API
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Convert an array of task type Definition objects (from the `/TaskType` API)
+ * into PictFlowCard constructor configs, applying visual overrides and
+ * appending the Start / End flow markers.
+ *
+ * @param {Array} pDefinitions - Task type definitions fetched from the server.
+ * @returns {Array} Ready-to-use PictFlowCard config objects.
+ */
+function generateCardConfigs(pDefinitions)
+{
+	let tmpConfigs = [];
+
+	for (let i = 0; i < pDefinitions.length; i++)
+	{
+		let tmpOverrides = _CardOverrides[pDefinitions[i].Hash] || null;
+		let tmpCardConfig = generateCardConfig(pDefinitions[i], tmpOverrides);
+
+		if (tmpCardConfig)
+		{
+			// Inject help content if available for this card code
+			if (_CardHelpContent[tmpCardConfig.Code])
+			{
+				tmpCardConfig.Help = _CardHelpContent[tmpCardConfig.Code];
+			}
+			tmpConfigs.push(tmpCardConfig);
+		}
+	}
+
+	// Append the 2 flow marker cards with help content
+	for (let i = 0; i < _FlowMarkerConfigs.length; i++)
+	{
+		let tmpMarkerConfig = Object.assign({}, _FlowMarkerConfigs[i]);
+		if (_CardHelpContent[tmpMarkerConfig.Code])
+		{
+			tmpMarkerConfig.Help = _CardHelpContent[tmpMarkerConfig.Code];
+		}
+		tmpConfigs.push(tmpMarkerConfig);
+	}
+
+	return tmpConfigs;
+}
+
+module.exports = { generateCardConfigs, CardOverrides: _CardOverrides, FlowMarkerConfigs: _FlowMarkerConfigs };