ultravisor 1.0.3 → 1.0.8

package/webinterface/docs/card-help/meadow-count.md

@@ -0,0 +1,24 @@
+# Meadow Count
+
+Counts records for an entity via a Meadow REST API endpoint, with optional filtering.
+
+## Settings
+
+- **Entity** — Entity (table) name.
+- **Endpoint** — Base URL of the Meadow API server.
+- **Destination** — State address to store the count value.
+- **Headers** — JSON string of request headers for authentication.
+- **Filter** — Meadow filter expression to count only matching records.
+
+## Outputs
+
+- **Count** — Number of records matching the criteria.
+
+## Events
+
+- **Complete** — Fires after the count is retrieved.
+- **Error** — Fires on failure.
+
+## Tips
+
+Use Meadow Count before **Meadow Reads** 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.

package/webinterface/docs/card-help/meadow-create.md

@@ -0,0 +1,24 @@
+# Meadow Create
+
+Creates a new record via a Meadow REST API endpoint.
+
+## Settings
+
+- **Entity** — Entity (table) name.
+- **Endpoint** — Base URL of the Meadow API server.
+- **DataAddress** — State address of the object containing the record data to create.
+- **Headers** — JSON string of request headers for authentication.
+- **Destination** — State address to store the created record (includes server-generated fields like ID).
+
+## Outputs
+
+- **Created** — The newly created record object with its assigned ID.
+
+## Events
+
+- **Complete** — Fires after the record is created.
+- **Error** — Fires on failure.
+
+## Tips
+
+Build the record data with **Set Values** or **Template String** before passing it to Meadow Create. The created record output includes the server-assigned ID, which you can use in subsequent steps.

package/webinterface/docs/card-help/meadow-delete.md

@@ -0,0 +1,19 @@
+# Meadow Delete
+
+Deletes a record by its ID via a Meadow REST API endpoint.
+
+## Settings
+
+- **Entity** — Entity (table) name.
+- **Endpoint** — Base URL of the Meadow API server.
+- **RecordID** — The ID of the record to delete.
+- **Headers** — JSON string of request headers for authentication.
+
+## Events
+
+- **Done** — Fires after the record is deleted.
+- **Error** — Fires on failure.
+
+## Tips
+
+Meadow Delete is permanent — consider adding a **Value Input** confirmation step before deleting records in user-facing workflows. Build the RecordID dynamically with template expressions when deleting records identified by earlier processing steps.

package/webinterface/docs/card-help/meadow-read.md

@@ -0,0 +1,24 @@
+# Meadow Read
+
+Reads a single record by its ID from a Meadow REST API endpoint.
+
+## Settings
+
+- **Entity** — Entity (table) name to query.
+- **Endpoint** — Base URL of the Meadow API server.
+- **RecordID** — The ID of the record to retrieve.
+- **Destination** — State address to store the retrieved record.
+- **Headers** — JSON string of additional request headers for authentication.
+
+## Outputs
+
+- **Record** — The retrieved record object.
+
+## Events
+
+- **Complete** — Fires after the record is retrieved.
+- **Error** — Fires if the record is not found or the request fails.
+
+## Tips
+
+Use **Set Values** or **Template String** to build the RecordID dynamically from other state values. Pair with **Meadow Update** to read-modify-write a record.

package/webinterface/docs/card-help/meadow-reads.md

@@ -0,0 +1,27 @@
+# Meadow Reads
+
+Reads multiple records from a Meadow REST API endpoint, with optional filtering and pagination.
+
+## Settings
+
+- **Entity** — Entity (table) name to query.
+- **Endpoint** — Base URL of the Meadow API server.
+- **Filter** — Meadow filter expression to narrow the result set (e.g. `FBV~IDUser~EQ~42~0~`).
+- **Destination** — State address to store the records array.
+- **Headers** — JSON string of request headers for authentication.
+- **PageSize** — Number of records per page (default `100`).
+- **PageNumber** — Zero-based page number (default `0`).
+
+## Outputs
+
+- **Records** — Array of retrieved record objects.
+- **RecordCount** — Number of records returned.
+
+## Events
+
+- **Complete** — Fires after records are retrieved.
+- **Error** — Fires on request failure.
+
+## Tips
+
+Use the Meadow filter expression to limit results server-side for better performance. Combine with **Split Execute** to process each record individually, or with **Comprehension Intersect** to join data from two entities.

package/webinterface/docs/card-help/meadow-update.md

@@ -0,0 +1,24 @@
+# Meadow Update
+
+Updates an existing record via a Meadow REST API endpoint.
+
+## Settings
+
+- **Entity** — Entity (table) name.
+- **Endpoint** — Base URL of the Meadow API server.
+- **DataAddress** — State address of the record data to update. Must include the record's ID field.
+- **Headers** — JSON string of request headers for authentication.
+- **Destination** — State address to store the updated record.
+
+## Outputs
+
+- **Updated** — The updated record object.
+
+## Events
+
+- **Complete** — Fires after the update.
+- **Error** — Fires on failure.
+
+## Tips
+
+Use **Meadow Read** first to load the current record, modify the fields you need with **Set Values**, then pass the modified object to Meadow Update. The data object must include the record's primary key field.

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

@@ -0,0 +1,27 @@
+# Parse CSV
+
+Parses CSV text into an array of records (objects with field names as keys).
+
+## Settings
+
+- **SourceAddress** — State address containing the CSV text to parse.
+- **Delimiter** — Column delimiter character (default `,`).
+- **HasHeaders** — When `true`, the first row provides field names. When `false`, fields are indexed numerically.
+- **Destination** — State address to store the parsed records array.
+- **QuoteCharacter** — Character used to quote fields that contain the delimiter (default `"`).
+- **TrimFields** — Trim leading/trailing whitespace from field values.
+- **SkipEmptyLines** — Skip blank lines in the input.
+
+## Outputs
+
+- **Records** — Array of parsed row objects.
+- **ColumnCount** — Number of columns detected.
+- **Headers** — Array of header names from the first row.
+
+## Events
+
+- **Complete** — Fires after parsing.
+
+## Tips
+
+Chain **Read File** → **Parse CSV** → **CSV Transform** for a complete data import pipeline. Use TrimFields and SkipEmptyLines to handle messy real-world CSV exports cleanly.

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

@@ -0,0 +1,29 @@
+# Read File Buffered
+
+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.
+
+## Settings
+
+- **FilePath** — Path to the file to read.
+- **Encoding** — Character encoding (default `utf8`).
+- **MaxBufferSize** — Maximum bytes per chunk (default `65536`).
+- **SplitCharacter** — 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.
+- **ByteOffset** — Byte offset to start reading from. Use `0` for the first chunk and feed the output ByteOffset back for continuation.
+
+## Outputs
+
+- **FileContent** — Content of the current chunk.
+- **BytesRead** — Bytes in this chunk.
+- **ByteOffset** — Updated byte offset for the next read.
+- **IsComplete** — `true` when the entire file has been read.
+- **FileName** — Base name of the file.
+- **TotalFileSize** — Total size of the file in bytes.
+
+## Events
+
+- **ReadComplete** — Fires when a chunk is read successfully.
+- **Error** — Fires on read failure.
+
+## Tips
+
+Wire the ByteOffset output back to the ByteOffset setting input and use an **If Conditional** on IsComplete to create a read loop. This pattern lets you process files of any size line-by-line or paragraph-by-paragraph.

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

@@ -0,0 +1,24 @@
+# Read File
+
+Reads a file from the local file system into operation state.
+
+## Settings
+
+- **FilePath** — Path to the file to read. Supports Pict template expressions for dynamic paths.
+- **Encoding** — Character encoding (default `utf8`). Use `binary` for non-text files.
+- **MaxBytes** — Maximum bytes to read. Set to `0` for unlimited.
+
+## Outputs
+
+- **FileContent** — The full text content of the file.
+- **BytesRead** — Number of bytes that were read.
+- **FileName** — The base name of the file (no directory).
+
+## Events
+
+- **ReadComplete** — Fires after a successful read.
+- **Error** — Fires if the file cannot be found or read.
+
+## Tips
+
+For very large files, use **Read File Buffered** instead to process content in chunks. Use MaxBytes as a safety limit to avoid loading unexpectedly large files into memory.

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

@@ -0,0 +1,21 @@
+# Read JSON
+
+Reads a JSON file from disk, parses it, and stores the resulting object in operation state.
+
+## Settings
+
+- **FilePath** — Path to the JSON file.
+- **Destination** — State address to store the parsed data. If empty, data is stored at the default output address.
+
+## Outputs
+
+- **Data** — The parsed JSON object or array.
+
+## Events
+
+- **Complete** — Fires after successful read and parse.
+- **Error** — Fires if the file is missing or contains invalid JSON.
+
+## Tips
+
+Pair with **Write JSON** 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.

package/webinterface/docs/card-help/replace-string.md

@@ -0,0 +1,25 @@
+# Replace String
+
+Replaces all occurrences of a search string within the input text.
+
+## Settings
+
+- **InputString** — The source text to search within. Supports Pict template expressions.
+- **SearchString** — The text or pattern to find.
+- **ReplaceString** — The replacement text (empty string to delete matches).
+- **UseRegex** — When `true`, treats SearchString as a regular expression.
+- **CaseSensitive** — Case-sensitive matching (default `true`).
+
+## Outputs
+
+- **ReplacedString** — The result after all replacements.
+- **ReplacementCount** — Number of replacements made.
+
+## Events
+
+- **ReplaceComplete** — Fires after replacement.
+- **Error** — Fires on failure (e.g. invalid regex).
+
+## Tips
+
+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.

package/webinterface/docs/card-help/rest-request.md

@@ -0,0 +1,30 @@
+# REST Request
+
+Performs a fully configurable HTTP request with support for any method, custom content types, request bodies, retries, and timeout control.
+
+## Settings
+
+- **URL** — The URL to request.
+- **Method** — HTTP method: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, etc. (default `GET`).
+- **ContentType** — Content-Type header value (default `application/json`).
+- **Headers** — JSON string of additional request headers.
+- **Body** — Request body as a JSON string or raw text.
+- **Destination** — State address to store the response.
+- **Retries** — Number of retries on failure (default `0`).
+- **TimeoutMs** — Request timeout in milliseconds (default `30000`).
+- **RetryDelayMs** — Delay between retry attempts in milliseconds (default `1000`).
+
+## Outputs
+
+- **Response** — The response data.
+- **StatusCode** — HTTP response status code.
+- **ResponseHeaders** — JSON string of response headers.
+
+## Events
+
+- **Complete** — Fires on success.
+- **Error** — Fires on failure after all retries are exhausted.
+
+## Tips
+
+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.

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

@@ -0,0 +1,26 @@
+# Send JSON
+
+Sends JSON data to a URL via HTTP POST or PUT.
+
+## Settings
+
+- **URL** — The URL to send data to.
+- **Method** — HTTP method: `POST` or `PUT` (default `POST`).
+- **DataAddress** — State address of the object to send as the request body.
+- **Headers** — JSON string of additional request headers.
+- **Destination** — State address to store the response data.
+- **TimeoutMs** — Request timeout in milliseconds (default `30000`).
+
+## Outputs
+
+- **Response** — The parsed response data.
+- **StatusCode** — HTTP response status code.
+
+## Events
+
+- **Complete** — Fires on success.
+- **Error** — Fires on failure.
+
+## Tips
+
+Use Send JSON for creating or updating resources via REST APIs. For more control over the request (custom Content-Type, DELETE method, retries), use **REST Request** instead.

package/webinterface/docs/card-help/set-values.md

@@ -0,0 +1,16 @@
+# Set Values
+
+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.
+
+## Settings
+
+- **Mappings** — An array of mapping objects. Each mapping has a `To` address (where to write) and either a `Value` (literal) or `From` address (copy from state).
+
+## Events
+
+- **Complete** — Fires after all mappings are applied.
+- **Error** — Fires if a mapping fails.
+
+## Tips
+
+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.

package/webinterface/docs/card-help/split-execute.md

@@ -0,0 +1,35 @@
+# Split Execute
+
+Splits a string by a delimiter and processes each token through a sub-graph, acting as a loop iterator within the flow.
+
+## Settings
+
+- **InputString** — The string to split. Supports Pict template expressions.
+- **SplitDelimiter** — Delimiter to split on (default newline `\n`).
+- **SkipEmpty** — When `true`, skips empty tokens after splitting.
+- **TrimTokens** — When `true`, trims whitespace from each token.
+
+## Outputs
+
+- **CurrentToken** — The current token being processed.
+- **TokenIndex** — Zero-based index of the current token.
+- **TokenCount** — Total number of tokens.
+- **CompletedCount** — Number of tokens processed so far.
+
+## Events
+
+- **TokenDataSent** — Fires for each token, sending it through the sub-graph.
+- **CompletedAllSubtasks** — Fires after all tokens have been processed.
+- **Error** — Fires on failure.
+
+## How It Works
+
+1. The input string is split into tokens by the delimiter.
+2. For each token, **TokenDataSent** fires with the token data in state.
+3. Connect the downstream processing graph to TokenDataSent.
+4. Wire the end of your processing graph back to the **StepComplete** event input to advance to the next token.
+5. After all tokens are processed, **CompletedAllSubtasks** fires.
+
+## Tips
+
+Split Execute is the primary looping mechanism in Ultravisor flows. Use it with **List Files** output to process each file, or with newline-delimited text to process line-by-line.

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

@@ -0,0 +1,11 @@
+# Start
+
+Entry point for the workflow. Every operation flow begins with a Start card.
+
+## Events
+
+- **Out** — Fires when the operation begins execution. Connect this to the first processing card in your flow.
+
+## Tips
+
+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.

package/webinterface/docs/card-help/string-appender.md

@@ -0,0 +1,22 @@
+# String Appender
+
+Appends a string to an existing value at a specified state address. Useful for building up output incrementally across loop iterations or multiple steps.
+
+## Settings
+
+- **InputString** — The text to append. Supports Pict template expressions.
+- **OutputAddress** — State address of the string to append to.
+- **AppendNewline** — When `true`, appends a newline character after the input string.
+- **Separator** — String inserted between the existing content and new content. Overrides AppendNewline when set.
+
+## Outputs
+
+- **AppendedString** — The full accumulated string after appending.
+
+## Events
+
+- **Completed** — Fires after the append.
+
+## Tips
+
+Combine with **Split Execute** to build a report line by line. Use AppendNewline for log-style output or Separator for CSV-style concatenation with a custom delimiter.

package/webinterface/docs/card-help/template-string.md

@@ -0,0 +1,21 @@
+# Template String
+
+Processes a Pict template string against the current operation state, resolving expressions like `{~D:Record.Name~}` into their runtime values.
+
+## Settings
+
+- **Template** — A Pict template string containing `{~D:...~}` expressions that reference state addresses.
+- **Destination** — State address to store the rendered result. If empty, the result is available at the default output.
+
+## Outputs
+
+- **Result** — The fully rendered template output.
+
+## Events
+
+- **Complete** — Fires after rendering.
+- **Error** — Fires if template parsing fails.
+
+## Tips
+
+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.

package/webinterface/docs/card-help/value-input.md

@@ -0,0 +1,24 @@
+# Value Input
+
+Pauses flow execution and prompts the user for input. The flow resumes when the user provides a value or cancels.
+
+## Settings
+
+- **PromptMessage** — The message displayed to the user (default: "Please provide a value:").
+- **OutputAddress** — State address where the user's input will be stored.
+- **InputType** — Type of input control: `text`, `number`, `boolean`, or `select` (default `text`).
+- **DefaultValue** — Pre-filled default value.
+- **Options** — JSON array of allowed values when InputType is `select`.
+
+## Outputs
+
+- **InputValue** — The value provided by the user.
+
+## Events
+
+- **ValueInputComplete** — Fires when the user submits a value.
+- **Cancelled** — Fires if the user cancels without providing input.
+
+## Tips
+
+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 `select` InputType with Options for constrained choices.

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

@@ -0,0 +1,27 @@
+# Write File
+
+Writes text content to a file on disk.
+
+## Settings
+
+- **FilePath** — Path to the output file. Intermediate directories are created automatically.
+- **Content** — The text content to write. Supports Pict template expressions.
+- **Encoding** — Character encoding (default `utf8`).
+- **Append** — When `true`, appends to an existing file instead of overwriting it.
+- **LineEnding** — Force a line ending style: `lf`, `crlf`, or leave empty for no conversion.
+
+## Outputs
+
+- **FileLocation** — The path as specified (may be relative).
+- **FileName** — The base file name only.
+- **FilePath** — The fully resolved absolute path.
+- **BytesWritten** — Number of bytes written.
+
+## Events
+
+- **WriteComplete** — Fires on success.
+- **Error** — Fires on write failure.
+
+## Tips
+
+Use Append mode with a **String Appender** to build log files or accumulate output across loop iterations.

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

@@ -0,0 +1,28 @@
+# Write JSON
+
+Serializes a state object to JSON and writes it to a file on disk.
+
+## Settings
+
+- **FilePath** — Path to the output JSON file.
+- **DataAddress** — State address of the data to serialize. If empty, uses the full operation state.
+- **PrettyFormat** — Pretty-print with indentation (default `true`).
+- **IndentType** — Indent character: `tab` or `space` (default `tab`).
+- **IndentCount** — Number of indent characters per level (default `1`).
+- **SortKeys** — Alphabetically sort object keys for deterministic output.
+
+## Outputs
+
+- **FileLocation** — The path as specified.
+- **FileName** — The base file name only.
+- **FilePath** — The fully resolved absolute path.
+- **BytesWritten** — Number of bytes written.
+
+## Events
+
+- **Done** — Fires on success.
+- **Error** — Fires on write failure.
+
+## Tips
+
+Enable SortKeys for config files that will be compared across versions or stored in version control.

package/webinterface/html/index.html

@@ -10,9 +10,14 @@
 
 		<!-- Application Stylesheet -->
 		<link href="css/ultravisor.css" rel="stylesheet">
+		<!-- Theme Definitions (CSS Custom Properties) -->
+		<link href="css/ultravisor-themes.css" rel="stylesheet">
 		<!-- PICT Dynamic View CSS Container -->
 		<style id="PICT-CSS"></style>
 
+		<!-- Apply saved theme before first paint to prevent flash -->
+		<script>(function(){var t=localStorage.getItem('ultravisor-theme');if(t&&t!=='desert-dusk')document.body.dataset.theme=t;})();</script>
+
 		<!-- Load the PICT library -->
 		<script src="./js/pict.min.js" type="text/javascript"></script>
 		<!-- Bootstrap the Application -->

package/webinterface/package.json

@@ -5,6 +5,7 @@
 	"main": "source/Pict-Application-Ultravisor.js",
 	"scripts": {
 		"start": "node source/Pict-Application-Ultravisor.js",
+		"prebuild": "node ./node_modules/pict-section-flow/scripts/generate-card-help.js ./docs/card-help ./source/card-help-content.js",
 		"build": "npx quack build && npx quack copy"
 	},
 	"author": "steven velozo <steven@velozo.com>",
@@ -12,12 +13,16 @@
 	"dependencies": {
 		"pict": "^1.0.343",
 		"pict-application": "^1.0.28",
-		"pict-router": "^1.0.4",
-		"pict-view": "^1.0.64",
-		"pict-provider": "^1.0.3"
+		"pict-docuserve": "^0.0.32",
+		"pict-provider": "^1.0.3",
+		"pict-router": "^1.0.7",
+		"pict-section-content": "^0.0.6",
+		"pict-section-flow": "file:../../../pict/pict-section-flow",
+		"pict-section-form": "^1.0.194",
+		"pict-view": "^1.0.64"
 	},
 	"devDependencies": {
-		"quackage": "^1.0.41"
+		"quackage": "^1.0.59"
 	},
 	"copyFilesSettings": {
 		"whenFileExists": "overwrite"
@@ -34,6 +39,10 @@
 		{
 			"from": "./node_modules/pict/dist/*",
 			"to": "./dist/js/"
+		},
+		{
+			"from": "../docs/**",
+			"to": "./dist/docs/"
 		}
 	]
 }