ultravisor 1.0.3 → 1.0.8

package/webinterface/css/ultravisor.css

@@ -13,8 +13,8 @@ html, body {
 	font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
 	font-size: 16px;
 	line-height: 1.5;
-	color: #e0e0e0;
-	background-color: #1a1a2e;
+	color: var(--uv-text);
+	background-color: var(--uv-bg-base);
 	-webkit-font-smoothing: antialiased;
 	-moz-osx-font-smoothing: grayscale;
 }
@@ -23,16 +23,16 @@ html, body {
 h1, h2, h3, h4, h5, h6 {
 	margin-top: 0;
 	line-height: 1.3;
-	color: #f0f0f0;
+	color: var(--uv-text-heading);
 }
 
 a {
-	color: #4fc3f7;
+	color: var(--uv-link);
 	text-decoration: none;
 }
 
 a:hover {
-	color: #81d4fa;
+	color: var(--uv-link-hover);
 }
 
 /* Form elements */
@@ -40,16 +40,16 @@ input, select, textarea {
 	font-family: inherit;
 	font-size: 0.9em;
 	padding: 0.5em 0.75em;
-	border: 1px solid #3a3a5c;
+	border: 1px solid var(--uv-border);
 	border-radius: 4px;
-	background-color: #16213e;
-	color: #e0e0e0;
+	background-color: var(--uv-bg-surface);
+	color: var(--uv-text);
 	outline: none;
 	transition: border-color 0.15s;
 }
 
 input:focus, select:focus, textarea:focus {
-	border-color: #4fc3f7;
+	border-color: var(--uv-border-focus);
 }
 
 textarea {
@@ -79,11 +79,11 @@ table {
 th, td {
 	text-align: left;
 	padding: 0.6em 0.75em;
-	border-bottom: 1px solid #2a2a4a;
+	border-bottom: 1px solid var(--uv-border-subtle);
 }
 
 th {
-	color: #9e9ec0;
+	color: var(--uv-text-secondary);
 	font-weight: 600;
 	font-size: 0.8em;
 	text-transform: uppercase;
@@ -101,16 +101,39 @@ th {
 }
 
 ::-webkit-scrollbar-track {
-	background: #16213e;
+	background: var(--uv-scrollbar-track);
 }
 
 ::-webkit-scrollbar-thumb {
-	background: #3a3a5c;
+	background: var(--uv-scrollbar-thumb);
 	border-radius: 4px;
 }
 
 ::-webkit-scrollbar-thumb:hover {
-	background: #4a4a6c;
+	background: var(--uv-scrollbar-thumb-hover);
+}
+
+/* Flow panel overrides — restore light inputs inside the white panel */
+.pict-flow-panel input,
+.pict-flow-panel select,
+.pict-flow-panel textarea {
+	background-color: #fff;
+	color: #333;
+	border: 1px solid #ccc;
+}
+
+.pict-flow-panel input:focus,
+.pict-flow-panel select:focus,
+.pict-flow-panel textarea:focus {
+	border-color: var(--uv-border-focus);
+}
+
+.pict-flow-panel label {
+	color: #555;
+}
+
+.pict-flow-panel-body {
+	color: #333;
 }
 
 /* Responsive adjustments */

package/webinterface/docs/card-help/beacon-dispatch.md

@@ -0,0 +1,30 @@
+# Beacon Dispatch
+
+Dispatches a work item to a remote Beacon worker node. The task pauses until the Beacon completes execution and reports results back.
+
+## Settings
+
+- **RemoteCapability** — Required capability on the Beacon (e.g. `Shell`, `FileSystem`, `LLM`).
+- **RemoteAction** — Specific action within the capability (e.g. `Execute`, `Read`).
+- **Command** — Shell command to execute on the Beacon (when using Shell capability).
+- **Parameters** — Command-line parameters for the shell command.
+- **AffinityKey** — Worker affinity routing key. Requests with the same key are routed to the same Beacon.
+- **TimeoutMs** — Work item timeout in milliseconds (default `300000`).
+- **InputData** — JSON data to pass to the Beacon worker.
+- **Destination** — State address to write results to on completion.
+
+## Outputs
+
+- **StdOut** — Standard output from the Beacon execution.
+- **Result** — Result data from the Beacon.
+- **ExitCode** — Exit code of the remote command.
+- **BeaconID** — ID of the Beacon that executed the work.
+
+## Events
+
+- **Complete** — Fires when the Beacon finishes.
+- **Error** — Fires on failure or timeout.
+
+## Tips
+
+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.

package/webinterface/docs/card-help/command.md

@@ -0,0 +1,27 @@
+# Command
+
+Executes a shell command on the server and captures its output.
+
+## Settings
+
+- **Command** — The shell command to execute (e.g. `ls`, `git`, `python3`).
+- **Parameters** — Command-line arguments as a single string.
+- **Description** — Human-readable description of what this command does (for documentation only).
+- **WorkingDirectory** — Working directory for the command.
+- **TimeoutMs** — Command timeout in milliseconds (default `300000` — 5 minutes).
+- **Environment** — JSON object of environment variables to set for the command.
+
+## Outputs
+
+- **StdOut** — Standard output from the command.
+- **StdErr** — Standard error output from the command.
+- **ExitCode** — Exit code (0 typically indicates success).
+
+## Events
+
+- **Complete** — Fires when the command finishes.
+- **Error** — Fires if the command fails to start or times out.
+
+## Tips
+
+Use an **If Conditional** 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.

package/webinterface/docs/card-help/comprehension-intersect.md

@@ -0,0 +1,24 @@
+# Comprehension Intersect
+
+Intersects two arrays by matching records on a common field, similar to an SQL inner join.
+
+## Settings
+
+- **SourceAddressA** — State address of the first array.
+- **SourceAddressB** — State address of the second array.
+- **MatchField** — Field name to match records on. Records from both arrays with the same value in this field are merged.
+- **Destination** — State address to store the intersected results.
+- **JoinType** — Join type (default `inner`). Inner join returns only records that match in both arrays.
+
+## Outputs
+
+- **Result** — Array of merged record objects.
+- **MatchCount** — Number of matched records.
+
+## Events
+
+- **Complete** — Fires after intersection.
+
+## Tips
+
+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.

package/webinterface/docs/card-help/content-create-folder.md

@@ -0,0 +1,22 @@
+# Content Create Folder
+
+Creates a folder in the content directory on a remote Content System beacon.
+
+## Settings
+
+- **Path** — Relative folder path to create.
+- **AffinityKey** — Worker affinity key to route to a specific beacon.
+- **TimeoutMs** — Timeout in milliseconds (default `300000`).
+
+## Outputs
+
+- **StdOut** — Status message from the beacon.
+
+## Events
+
+- **Complete** — Fires after the folder is created.
+- **Error** — Fires on failure.
+
+## Tips
+
+Use Content Create Folder before **Content Save File** to ensure the target directory structure exists. The operation is idempotent — creating a folder that already exists succeeds without error.

package/webinterface/docs/card-help/content-list-files.md

@@ -0,0 +1,25 @@
+# Content List Files
+
+Lists files in a directory on a remote Content System beacon.
+
+## Settings
+
+- **Path** — Relative directory path within the content directory. Leave empty for the root.
+- **Pattern** — Glob pattern filter (e.g. `*.md`, `*.json`).
+- **Recursive** — When `true`, lists files in subdirectories.
+- **AffinityKey** — Worker affinity key to route to a specific beacon.
+- **TimeoutMs** — Timeout in milliseconds (default `300000`).
+
+## Outputs
+
+- **Files** — JSON array of file entries.
+- **StdOut** — Status message from the beacon.
+
+## Events
+
+- **Complete** — Fires after listing.
+- **Error** — Fires on failure.
+
+## Tips
+
+Use Content List Files to discover available content on a beacon before processing. Combine with **Split Execute** to iterate over the file list and read or transform each file.

package/webinterface/docs/card-help/content-read-file.md

@@ -0,0 +1,24 @@
+# Content Read File
+
+Reads a markdown or content file from a remote Content System beacon.
+
+## Settings
+
+- **FilePath** — Relative path within the content directory on the beacon.
+- **Destination** — State address to store the file content.
+- **AffinityKey** — Worker affinity key to route to a specific beacon.
+- **TimeoutMs** — Timeout in milliseconds (default `300000`).
+
+## Outputs
+
+- **Content** — The file content as a string.
+- **StdOut** — Status message from the beacon.
+
+## Events
+
+- **Complete** — Fires after a successful read.
+- **Error** — Fires if the file is not found or the beacon is unreachable.
+
+## Tips
+
+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 **Read File** instead.

package/webinterface/docs/card-help/content-save-file.md

@@ -0,0 +1,24 @@
+# Content Save File
+
+Saves content to a file on a remote Content System beacon.
+
+## Settings
+
+- **FilePath** — Relative path within the content directory.
+- **Content** — The file content to write. Supports Pict template expressions.
+- **AffinityKey** — Worker affinity key to route to a specific beacon.
+- **TimeoutMs** — Timeout in milliseconds (default `300000`).
+
+## Outputs
+
+- **FilePath** — Path of the saved file.
+- **StdOut** — Status message from the beacon.
+
+## Events
+
+- **Complete** — Fires after a successful save.
+- **Error** — Fires on failure.
+
+## Tips
+
+Use Content Save File to publish generated content (reports, processed data, rendered templates) to a Content System. Pair with **Content Read File** to read-modify-write content files on a beacon.

package/webinterface/docs/card-help/copy-file.md

@@ -0,0 +1,25 @@
+# Copy File
+
+Copies a file from a source path to a target path.
+
+## Settings
+
+- **Source** — Source file path.
+- **TargetFile** — Destination file path.
+- **Overwrite** — Allow overwriting an existing target file (default `true`).
+
+## Outputs
+
+- **FileLocation** — The target path as specified.
+- **FileName** — The target file name only.
+- **FilePath** — The fully resolved absolute target path.
+- **BytesCopied** — Size of the copied file in bytes.
+
+## Events
+
+- **Done** — Fires on successful copy.
+- **Error** — Fires if the source is missing or the target cannot be written.
+
+## Tips
+
+Set Overwrite to `false` to protect existing files from accidental replacement. Both Source and TargetFile support Pict template expressions for dynamic paths.

package/webinterface/docs/card-help/csv-transform.md

@@ -0,0 +1,24 @@
+# CSV Transform
+
+Transforms an array of parsed CSV records by applying field mappings, filters, and output field selection.
+
+## Settings
+
+- **SourceAddress** — State address of the records array to transform.
+- **Destination** — State address to store the transformed records.
+- **Delimiter** — Delimiter for re-serialization (default `,`).
+- **FieldMapping** — JSON array of mapping objects with `From`, `To`, and optional `Template` properties for field renaming and transformation.
+- **FilterExpression** — An expression to filter rows. Only rows where the expression evaluates to true are included.
+- **OutputFields** — JSON array of field names to include in the output. Omit to include all fields.
+
+## Outputs
+
+- **Records** — The transformed records array.
+
+## Events
+
+- **Complete** — Fires after transformation.
+
+## Tips
+
+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.

package/webinterface/docs/card-help/end.md

@@ -0,0 +1,11 @@
+# End
+
+Termination point for the workflow. When execution reaches the End card, the operation completes.
+
+## Events
+
+- **In** — Receives the final event from the flow. Accepts up to 5 incoming connections.
+
+## Tips
+
+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.

package/webinterface/docs/card-help/error-message.md

@@ -0,0 +1,16 @@
+# Error Message
+
+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.
+
+## Settings
+
+- **MessageTemplate** — The message text to log. Supports Pict template expressions for including state values (default: "An error occurred.").
+- **Level** — Log level: `error`, `warning`, `info`, or `debug` (default `error`).
+
+## Events
+
+- **Complete** — Fires after the message is logged. Execution continues normally.
+
+## Tips
+
+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 `info` level for progress markers and `debug` for development-time tracing.

package/webinterface/docs/card-help/expression-solver.md

@@ -0,0 +1,21 @@
+# Expression Solver
+
+Evaluates a mathematical or logical expression using the Fable ExpressionParser and stores the result in state.
+
+## Settings
+
+- **Expression** — The expression to evaluate. Can reference state values by address.
+- **Destination** — State address to store the evaluation result.
+
+## Outputs
+
+- **Result** — The computed result as a string.
+
+## Events
+
+- **Complete** — Fires after evaluation.
+- **Error** — Fires on parse or evaluation failure.
+
+## Tips
+
+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.

package/webinterface/docs/card-help/get-json.md

@@ -0,0 +1,24 @@
+# Get JSON
+
+Performs an HTTP GET request and parses the response body as JSON.
+
+## Settings
+
+- **URL** — The URL to request. Supports Pict template expressions for dynamic URLs.
+- **Headers** — JSON string of additional request headers (e.g. `{"Authorization": "Bearer ..."}`).
+- **Destination** — State address to store the parsed response data.
+- **TimeoutMs** — Request timeout in milliseconds (default `30000`).
+
+## Outputs
+
+- **Data** — The parsed JSON response object.
+- **StatusCode** — HTTP response status code.
+
+## Events
+
+- **Complete** — Fires on a successful response.
+- **Error** — Fires on network failure, timeout, or non-2xx status.
+
+## Tips
+
+For APIs requiring authentication, use **Set Values** to build the Headers JSON from stored credentials before connecting to the Headers setting input. Use the StatusCode output with an **If Conditional** to handle different HTTP response codes.

package/webinterface/docs/card-help/get-text.md

@@ -0,0 +1,24 @@
+# Get Text
+
+Performs an HTTP GET request and returns the response body as plain text.
+
+## Settings
+
+- **URL** — The URL to request.
+- **Destination** — State address to store the response text.
+- **Headers** — JSON string of additional request headers.
+- **TimeoutMs** — Request timeout in milliseconds (default `30000`).
+
+## Outputs
+
+- **Data** — The response body as a string.
+- **StatusCode** — HTTP response status code.
+
+## Events
+
+- **Complete** — Fires on a successful response.
+- **Error** — Fires on network failure or timeout.
+
+## Tips
+
+Use Get Text for non-JSON responses: HTML pages, CSV downloads, plain text APIs, or XML feeds. Pipe the output into **Parse CSV** for CSV data or **Replace String** for text processing.

package/webinterface/docs/card-help/histogram.md

@@ -0,0 +1,23 @@
+# Histogram
+
+Computes a frequency distribution over a specific field in a dataset array.
+
+## Settings
+
+- **SourceAddress** — State address of the data array to analyze.
+- **Field** — Field name to compute frequencies for (default `score`).
+- **Bins** — Number of bins for numeric data (default `5`).
+- **Destination** — State address to store the statistics object.
+- **SortBy** — Sort frequency results by `count` or `key`.
+
+## Outputs
+
+- **Stats** — An object containing the frequency distribution, bin boundaries, and summary statistics.
+
+## Events
+
+- **Complete** — Fires after computation.
+
+## Tips
+
+Use Histogram after parsing or loading a dataset to get a quick statistical overview. Combine with **Template String** to generate a text-based report of the distribution.

package/webinterface/docs/card-help/if-conditional.md

@@ -0,0 +1,23 @@
+# If Conditional
+
+Evaluates a condition and branches execution to the True or False output. This is the primary decision-making card in a flow.
+
+## Settings
+
+- **DataAddress** — State address of the value to test.
+- **CompareValue** — Value to compare against.
+- **Operator** — Comparison operator: `==`, `!=`, `>`, `<`, `>=`, `<=`, `contains`, `startsWith`, `endsWith`. Default `==`.
+- **Expression** — A full expression string. When set, DataAddress/CompareValue/Operator are ignored and the expression is evaluated directly.
+
+## Outputs
+
+- **Result** — Boolean result of the evaluation.
+
+## Events
+
+- **True** — Fires when the condition is true.
+- **False** — Fires when the condition is false.
+
+## Tips
+
+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.

package/webinterface/docs/card-help/launch-operation.md

@@ -0,0 +1,25 @@
+# Launch Operation
+
+Executes a child operation by its hash, with isolated operation state. This enables modular flow composition by calling one operation from within another.
+
+## Settings
+
+- **OperationHash** — The hash identifier of the operation to launch.
+- **InputData** — JSON data to pass as input to the child operation.
+- **TimeoutMs** — Maximum execution time in milliseconds. Set to `0` for unlimited.
+- **InheritGlobalState** — When `true` (default), copies the parent's GlobalState into the child operation.
+
+## Outputs
+
+- **Result** — The result data returned by the child operation.
+- **Status** — Final status of the child operation.
+- **ElapsedMs** — Execution time of the child operation in milliseconds.
+
+## Events
+
+- **Completed** — Fires when the child operation finishes.
+- **Error** — Fires if the child operation fails or times out.
+
+## Tips
+
+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.

package/webinterface/docs/card-help/list-files.md

@@ -0,0 +1,25 @@
+# List Files
+
+Lists files in a directory with optional glob pattern filtering.
+
+## Settings
+
+- **Folder** — Directory path to list.
+- **Pattern** — Glob pattern filter (e.g. `*.txt`, `*.json`). Default `*` matches all files.
+- **Destination** — State address to store the resulting file list.
+- **Recursive** — When `true`, includes files in subdirectories.
+- **IncludeDirectories** — When `true`, includes directory entries in the results.
+
+## Outputs
+
+- **Files** — Array of file name strings matching the pattern.
+- **FileCount** — Number of entries found.
+
+## Events
+
+- **Complete** — Fires after listing is complete.
+- **Error** — Fires if the directory cannot be read.
+
+## Tips
+
+Use with **Split Execute** 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.

package/webinterface/docs/card-help/llm-chat-completion.md

@@ -0,0 +1,43 @@
+# LLM Chat Completion
+
+Sends messages to a large language model and returns the completion. Supports multi-turn conversation history with persistence across operation runs.
+
+## Settings
+
+- **SystemPrompt** — System prompt text that sets the LLM's behavior and context.
+- **UserPrompt** — User prompt text for the current turn.
+- **Messages** — JSON array of message objects `[{role, content}]` for direct control over the conversation. Overrides SystemPrompt/UserPrompt when set.
+- **Model** — Override the default model name.
+- **Temperature** — Sampling temperature (0–2). Lower values are more deterministic.
+- **MaxTokens** — Maximum tokens to generate (default `4096`).
+- **TopP** — Nucleus sampling parameter.
+- **StopSequences** — JSON array of sequences that stop generation.
+- **ResponseFormat** — Set to `json_object` to force JSON output.
+- **InputAddress** — State address to read additional context data from (appended to UserPrompt).
+- **Destination** — State address to write the completion text to.
+
+## Conversation History
+
+- **ConversationAddress** — State address to store message history for multi-turn conversations.
+- **AppendToConversation** — Append this exchange to history (default `true` when ConversationAddress is set).
+- **ConversationMaxMessages** — Sliding window: maximum non-system messages to keep.
+- **ConversationMaxTokens** — Token budget for history (approximate, trims oldest messages).
+- **PersistConversation** — Copy conversation history to GlobalState for cross-operation persistence.
+- **ConversationPersistAddress** — GlobalState address for persistence.
+
+## Dispatch
+
+- **AffinityKey** — Route to a specific Beacon worker for consistent model access.
+- **TimeoutMs** — Timeout in milliseconds (default `120000`).
+
+## Outputs
+
+- **Content** — The LLM's response text.
+- **Model** — Model that generated the response.
+- **PromptTokens** / **CompletionTokens** / **TotalTokens** — Token usage statistics.
+- **FinishReason** — Why the completion ended (`stop`, `length`, etc.).
+- **BeaconID** — ID of the Beacon worker that executed the request.
+
+## Tips
+
+Use ConversationAddress with PersistConversation to build chatbots that maintain context across multiple operation runs. Set ResponseFormat to `json_object` when you need structured output that downstream cards can parse. Use Temperature `0` for deterministic, reproducible results.

package/webinterface/docs/card-help/llm-embedding.md

@@ -0,0 +1,24 @@
+# LLM Embedding
+
+Generates vector embeddings for text input using an LLM provider. Dispatches the work to a Beacon with LLM capability.
+
+## Settings
+
+- **Text** — The text to embed. Supports Pict template expressions.
+- **Model** — Override the default embedding model.
+- **Dimensions** — Requested embedding dimensions (model-dependent).
+- **InputAddress** — State address to read text from (alternative to Text setting).
+- **Destination** — State address to write the embedding vector to.
+- **AffinityKey** — Route to a specific Beacon worker.
+- **TimeoutMs** — Timeout in milliseconds (default `60000`).
+
+## Outputs
+
+- **Embedding** — JSON array of floating-point numbers representing the embedding vector.
+- **Dimensions** — Number of dimensions in the embedding.
+- **Model** — Model used for embedding.
+- **BeaconID** — ID of the Beacon that executed the work.
+
+## Tips
+
+Use embeddings for semantic search, clustering, or similarity comparisons. Store embeddings in a database via **Meadow Create** for later retrieval. Combine with **Expression Solver** or downstream processing to compute cosine similarity between vectors.

package/webinterface/docs/card-help/llm-tool-use.md

@@ -0,0 +1,39 @@
+# LLM Tool Use
+
+Sends messages to a large language model with tool (function) definitions, enabling the LLM to request tool calls that your flow can execute.
+
+## Settings
+
+- **SystemPrompt** — System prompt text.
+- **UserPrompt** — User prompt text.
+- **Messages** — JSON array of messages for direct conversation control.
+- **Tools** — JSON array of tool definitions describing available functions the LLM can call.
+- **Model** — Override model name.
+- **ToolChoice** — `auto` (LLM decides), `none` (no tools), or a specific tool name (default `auto`).
+- **Temperature** — Sampling temperature.
+- **MaxTokens** — Maximum tokens to generate.
+- **ConversationAddress** — State address for multi-turn history.
+- **AppendToConversation** — Append this exchange to history.
+- **InputAddress** — State address to read context data from.
+- **Destination** — State address to write completion content.
+- **AffinityKey** — Route to a specific Beacon worker.
+- **TimeoutMs** — Timeout in milliseconds (default `120000`).
+
+## Outputs
+
+- **Content** — The LLM's text response (may be empty if tool calls were made).
+- **ToolCalls** — JSON array of tool call objects with function names and arguments.
+- **Model** — Model that generated the response.
+- **FinishReason** — `stop` for normal completion, `tool_calls` when tools were invoked.
+- **PromptTokens** / **CompletionTokens** — Token usage.
+- **BeaconID** — Beacon worker ID.
+
+## Events
+
+- **Complete** — Fires when the LLM responds.
+- **ToolCall** — Fires when the LLM requests a tool call.
+- **Error** — Fires on failure.
+
+## Tips
+
+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.