retold 4.0.4 → 4.0.7

package/docs/architecture/documentation-style-guide.md

@@ -0,0 +1,65 @@
+# Retold Documentation Style Guide
+
+Style conventions for writing documentation within the Retold ecosystem. These apply to markdown files served through pict-docuserve in the `/docs/` directory.
+
+## Routing and Links
+
+Retold documentation uses **pict-docuserve** with hash-based routing, not standard docsify.
+
+- **Local page links:** `#/page/<path>` (e.g., `#/page/architecture/architecture.md`)
+- **Module doc links:** `#/doc/<group>/<module>` (e.g., `#/doc/pict/pict-section-form`)
+- **Links in subdirectory `.md` files** must use absolute paths from the docs root (no relative path resolution for `#/page/` routes)
+- **Anchor fragments** (`#heading-slug`) are not supported in cross-file links — do not use them
+
+## Markdown Conventions
+
+### Headings
+
+- Use `#` for the page title (one per file)
+- Use `##` for major sections
+- Use `###` for subsections
+- Do not skip heading levels
+
+### Code Blocks
+
+- Always specify the language for syntax highlighting
+- Use `javascript` (not `js`) for JavaScript blocks
+- Use `html` for HTML blocks
+- Use `bash` or `shell` for terminal commands
+
+### Module References
+
+When referencing a Retold module, link to its documentation:
+
+```markdown
+See [pict-section-form](#/doc/pict/pict-section-form) for details.
+```
+
+### Tone
+
+- Write in plain, direct language
+- Prefer active voice
+- Keep paragraphs short — aim for 2–4 sentences
+- Lead with the most important information
+
+## File Organization
+
+```
+docs/
+├── _sidebar.md          # Navigation sidebar
+├── _topbar.md           # Top navigation bar
+├── README.md            # Landing page
+├── architecture/        # Architecture and design docs
+├── modules/             # Module group overview pages
+├── examples/            # Example walkthroughs
+└── css/                 # Custom stylesheets
+```
+
+## Navigation
+
+The sidebar is defined in `_sidebar.md`. When adding new pages:
+
+1. Add the markdown file to the appropriate directory
+2. Add an entry in `_sidebar.md` under the correct section
+3. Use the `.md` extension in sidebar links for local pages
+4. Module links use the `/group/module/` format (no `.md`)

package/docs/architecture/example-app-style-guide.md

@@ -0,0 +1,154 @@
+# Pict Example App Style Guide
+
+## Red Rock Mesa Theme
+
+All Pict example applications use the **Red Rock Mesa** theme — a southwest-inspired design that makes it immediately obvious you are looking at a Pict example app.
+
+The theme is named for the Sedona red rock and Monument Valley landscape: deep sky teal headers, sienna accents, sandstone borders, and pale desert backgrounds.
+
+## Color Palette
+
+| Role | Color | Hex |
+|------|-------|-----|
+| **Deep Sky Teal** | Header background, table headers, headings | `#264653` |
+| **Red Rock** | Emphasis, alternate accent | `#B33030` |
+| **Sienna** | Primary accent, buttons, top borders, badge | `#E76F51` |
+| **Sienna Hover** | Button hover state | `#C45A3E` |
+| **Sandstone** | Borders, secondary headings | `#D4A373` |
+| **Pale Desert** | Page background, header text | `#FAEDCD` |
+| **Warm White** | Form container backgrounds | `#fff` |
+| **Desert Off-White** | Input backgrounds | `#FFFCF7` |
+| **Input Border** | Default input/textarea borders | `#D4C4A8` |
+| **Table Row Stripe** | Even row background | `#FFF9F0` |
+| **Table Row Border** | Cell bottom border | `#E8D9C0` |
+| **Shadow** | Container box-shadow | `rgba(38,70,83,0.08)` |
+
+## Standard Header
+
+Every example app includes a header bar with three elements:
+
+```html
+<div class="pict-example-header">
+    <div class="pict-example-badge">
+        <svg viewBox="0 0 16 16"><polygon points="8,1 10,6 16,6 11,9.5 13,15 8,11.5 3,15 5,9.5 0,6 6,6"/></svg>
+        Pict Example
+    </div>
+    <div class="pict-example-app-name">Your App Name</div>
+    <div class="pict-example-module">pict-section-form</div>
+</div>
+```
+
+- **Badge** (left): Sienna background with star icon and "PICT EXAMPLE" text — identifies this as a Pict example
+- **App Name** (center-left): The specific example application name in pale desert text
+- **Module Name** (right): The source module name in sandstone text, pushed to the far right
+
+## Page Structure
+
+```html
+<body>
+    <!-- 1. Header bar -->
+    <div class="pict-example-header">...</div>
+
+    <!-- 2. Content wrapper -->
+    <div class="pict-example-content">
+        <!-- 3. Optional action bar -->
+        <div class="pict-example-actions">
+            <button>Action</button>
+        </div>
+        <!-- 4. Form container (Pict renders into this) -->
+        <div id="Pict-Form-Container"></div>
+    </div>
+</body>
+```
+
+The content area has `1.5rem` padding and spans the full browser width — no max-width constraint, so wide tables and grids are usable at any viewport size.
+
+## Form Container
+
+The main form container has:
+
+- White background
+- Sandstone (`#D4A373`) border
+- **4px sienna top border** — the signature accent
+- 6px border radius
+- Subtle box shadow
+
+```css
+#Pict-Form-Container {
+    background: #fff;
+    border: 1px solid #D4A373;
+    border-top: 4px solid #E76F51;
+    border-radius: 6px;
+    padding: 1.25rem;
+    box-shadow: 0 2px 8px rgba(38,70,83,0.08);
+}
+```
+
+## Form Elements
+
+### Inputs and Selects
+
+All text inputs, number inputs, textareas, and selects get:
+
+- `1px solid #D4C4A8` border
+- `#FFFCF7` background (warm off-white)
+- `0.45rem 0.6rem` padding
+- `4px` border radius
+- On focus: sienna border with subtle sienna glow (`box-shadow: 0 0 0 2px rgba(231,111,81,0.15)`)
+
+### Labels
+
+- Deep sky teal (`#264653`)
+- `font-weight: 600`
+- `0.85rem` font size
+
+### Buttons
+
+Primary buttons use sienna:
+
+```css
+background: #E76F51;
+color: #fff;
+border: none;
+padding: 0.5rem 1.25rem;
+border-radius: 4px;
+font-weight: 600;
+```
+
+Secondary/action buttons use deep sky teal:
+
+```css
+background: #264653;
+color: #FAEDCD;
+```
+
+### Tables
+
+- Header row: deep sky teal background with pale desert text
+- Cell borders: `1px solid #E8D9C0`
+- Even rows: `#FFF9F0` background (subtle stripe)
+
+## Implementation Notes
+
+- **All CSS is inline** within `<style>` tags in each HTML file — no external CSS framework dependencies
+- The `<style id="PICT-CSS"></style>` tag must remain present for Pict's dynamic CSS injection
+- Theme CSS should come **after** the PICT-CSS tag so it can override dynamic styles if needed
+- Use the `box-sizing: border-box` reset on all elements
+- Font stack: `-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif`
+
+## Adding a New Example
+
+When creating a new example application:
+
+1. Copy the HTML structure from any existing themed example (e.g., `simple_form`)
+2. Update the `<title>` tag: `Your App Name - Pict Example`
+3. Update the header app name: `<div class="pict-example-app-name">Your App Name</div>`
+4. Update the module name if it differs from `pict-section-form`
+5. Keep all theme CSS intact — the inline styles are self-contained
+6. Add any app-specific CSS **after** the theme block with a comment separator
+
+## Exceptions
+
+- The **postcard_example** (`Das Postkard`) has its own distinct styling with Pure CSS and a sidebar navigation — it is excluded from the standard theme
+- Apps using third-party component CSS (TUI Grid, JSON Editor, etc.) should load those stylesheets **before** the theme `<style>` block so the theme can override as needed
+- The `complex_table` example preserves custom `.HasFancyHeaders` styles, adapted to use theme-compatible colors

package/docs/architecture/modules.md

@@ -41,7 +41,7 @@ An exhaustive list of every repository in the Retold suite, organized by group.
 | [tidings](/orator/tidings/) | `tidings` | Extensible reporting system for generating HTML, PDF, and other format reports |
 | [orator-conversion](/orator/orator-conversion/) | `orator-conversion` | File format conversion endpoints for Orator service servers |
 
-## Pict — MVC Tools (19 modules)
+## Pict — MVC Tools (20 modules)
 
 | Module | npm | Description |
 |--------|-----|-------------|
@@ -60,20 +60,31 @@ An exhaustive list of every repository in the Retold suite, organized by group.
 | [pict-section-recordset](/pict/pict-section-recordset/) | `pict-section-recordset` | CRUD record management views from Meadow endpoint schemas |
 | [pict-section-content](/pict/pict-section-content/) | `pict-section-content` | Markdown parsing and content rendering with Mermaid diagrams and KaTeX math |
 | [pict-section-form](/pict/pict-section-form/) | `pict-section-form` | Configuration-driven dynamic forms with 13+ input types and data marshaling |
+| [pict-section-objecteditor](/pict/pict-section-objecteditor/) | `pict-section-objecteditor` | Tree-based JSON object editor section for Pict views |
 | [pict-section-tuigrid](/pict/pict-section-tuigrid/) | `pict-section-tuigrid` | Toast UI Grid integration for tabular data display and editing |
+| [pict-section-markdowneditor](/pict/pict-section-markdowneditor/) | `pict-section-markdowneditor` | Segmented markdown editor built on CodeMirror v6 with rich previews |
 | [pict-router](/pict/pict-router/) | `pict-router` | Hash-based URL routing via Navigo with template string route functions |
 | [pict-serviceproviderbase](/pict/pict-serviceproviderbase/) | `pict-serviceproviderbase` | Base classes for Pict services with pre-initialization support |
 | [pict-terminalui](/pict/pict-terminalui/) | `pict-terminalui` | Blessed-based terminal interface for Pict views |
 
-## Utility — Build & Documentation Tools (4 modules)
+## Utility — Build & Documentation Tools (6 modules)
 
 | Module | npm | Description |
 |--------|-----|-------------|
+| [cachetrax](/utility/cachetrax/) | `cachetrax` | Hash-indexed object cache with O(1) lookups, time and size based expiration, and custom pruning |
 | [indoctrinate](/utility/indoctrinate/) | `indoctrinate` | Documentation scaffolding with content cataloging, label-based filtering, and multi-format output |
 | [manyfest](/utility/manyfest/) | `manyfest` | JSON manifest for consistent data description, validation, and address-based access across layers |
+| [precedent](/utility/precedent/) | `precedent` | Meta-templating engine with pattern-based start/end markers and word tree matching |
 | [quackage](/utility/quackage/) | `quackage` | Standardized build tool for browser bundles, transpilation, testing, and packaging |
 | [ultravisor](/utility/ultravisor/) | `ultravisor` | Process supervision with scheduled tasks, distributed nodes, and LLM integration |
 
+## Apps — Applications (2 modules)
+
+| Module | npm | Description |
+|--------|-----|-------------|
+| [retold-content-system](/apps/retold-content-system/) | `retold-content-system` | Content management system built on the Retold ecosystem |
+| [retold-remote](/apps/retold-remote/) | `retold-remote` | Remote access application built on the Retold ecosystem |
+
 ## Summary
 
 | Group | Count | Focus |
@@ -81,9 +92,10 @@ An exhaustive list of every repository in the Retold suite, organized by group.
 | Fable | 6 | Core ecosystem, DI, configuration, logging |
 | Meadow | 12 | Data access, ORM, query DSL, schema, connectors |
 | Orator | 6 | API server, HTTP, static files, proxy, reporting, conversion |
-| Pict | 19 | MVC, views, templates, forms, grids, routing, docs, TUI |
-| Utility | 4 | Build tools, manifests, docs, process supervision |
-| **Total** | **47** | |
+| Pict | 20 | MVC, views, templates, forms, grids, routing, docs, TUI |
+| Utility | 6 | Build tools, caching, templating, manifests, docs, process supervision |
+| Apps | 2 | Full-stack applications built on Retold |
+| **Total** | **52** | |
 
 ## GitHub Repositories
 

package/docs/architecture/templating/data-access.md

@@ -0,0 +1,196 @@
+# Data Access Expressions
+
+Data access expressions resolve values from Pict's address space and return them as strings. These are the most frequently used expressions in Jellyfish templates.
+
+## Data (D)
+
+Resolves a value from the address space and returns it as a string.
+
+**Tags:** `{~Data:ADDRESS~}` `{~D:ADDRESS~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| ADDRESS | Dot-notation path to resolve (e.g., `AppData.User.Name`, `Record.Title`) |
+
+**Examples:**
+
+```html
+<h1>{~D:AppData.PageTitle~}</h1>
+<p>Author: {~D:Record.Author~}</p>
+<span>{~D:Bundle.Config.Version~}</span>
+```
+
+```javascript
+_Pict.AppData.User = { Name: 'Alice' };
+_Pict.parseTemplate('Hello, {~D:AppData.User.Name~}!');
+// 'Hello, Alice!'
+
+_Pict.parseTemplate('{~D:Record.City~}', { City: 'Portland' });
+// 'Portland'
+```
+
+If the address resolves to `undefined`, returns an empty string.
+
+---
+
+## DataWithTemplateFallback (DWTF)
+
+Resolves a value from the address space. If the value is falsy or undefined, renders a fallback template by hash instead.
+
+**Tags:** `{~DataWithTemplateFallback:DATA_ADDRESS:FALLBACK_TEMPLATE_HASH~}` `{~DWTF:DATA_ADDRESS:FALLBACK_TEMPLATE_HASH~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| DATA_ADDRESS | Dot-notation path to resolve |
+| FALLBACK_TEMPLATE_HASH | Hash of a registered template to render if the value is falsy |
+
+**Examples:**
+
+```javascript
+_Pict.TemplateProvider.addTemplate('MissingTitle',
+	'<span class="empty">No title available</span>');
+
+_Pict.TemplateProvider.addTemplate('BookHeading',
+	'<h1>{~DWTF:Record.Title:MissingTitle~}</h1>');
+
+// With data present
+_Pict.parseTemplateByHash('BookHeading', { Title: 'Dune' });
+// '<h1>Dune</h1>'
+
+// Without data
+_Pict.parseTemplateByHash('BookHeading', { Title: undefined });
+// '<h1><span class="empty">No title available</span></h1>'
+```
+
+---
+
+## DataWithAbsoluteFallback (DWAF)
+
+Resolves a value from the address space. If the value is falsy or undefined, returns a literal fallback string.
+
+**Tags:** `{~DataWithAbsoluteFallback:DATA_ADDRESS^LITERAL_FALLBACK~}` `{~DWAF:DATA_ADDRESS^LITERAL_FALLBACK~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| DATA_ADDRESS | Dot-notation path to resolve |
+| LITERAL_FALLBACK | A literal string to return if the value is falsy (separated by `^`) |
+
+**Examples:**
+
+```html
+<h1>{~DWAF:Record.Title^Untitled Document~}</h1>
+<p>{~DWAF:Record.Author^Unknown Author~}</p>
+```
+
+```javascript
+_Pict.parseTemplate('{~DWAF:Record.Title^No Title~}', { Title: 'Dune' });
+// 'Dune'
+
+_Pict.parseTemplate('{~DWAF:Record.Title^No Title~}', {});
+// 'No Title'
+```
+
+The fallback is a plain string, not a template -- it is not parsed for further expressions.
+
+---
+
+## DataValueByKey (DVBK)
+
+Accesses an object using a dynamic key resolved from a data address. Useful when the property name to access is itself stored in data.
+
+**Tags:** `{~DataValueByKey:OBJECT_ADDRESS^KEY_ADDRESS~}` `{~DVBK:OBJECT_ADDRESS^KEY_ADDRESS~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| OBJECT_ADDRESS | Address of the object to access |
+| KEY_ADDRESS | Address containing the key string to use for the lookup (separated by `^`) |
+
+**Examples:**
+
+```javascript
+_Pict.AppData.StatusLabels = {
+	'active': 'Currently Active',
+	'inactive': 'No Longer Active',
+	'pending': 'Awaiting Approval'
+};
+
+_Pict.parseTemplate(
+	'{~DVBK:AppData.StatusLabels^Record.Status~}',
+	{ Status: 'pending' });
+// 'Awaiting Approval'
+```
+
+This is valuable for lookup tables and maps where the key comes from another data field.
+
+---
+
+## DataJson (DJ)
+
+Returns the resolved value serialized as a JSON string via `JSON.stringify()`. If the address is empty, serializes the entire Record.
+
+**Tags:** `{~DataJson:ADDRESS~}` `{~DJ:ADDRESS~}` or `{~DJ:~}` (for entire Record)
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| ADDRESS | Dot-notation path to resolve (optional; empty address returns the full Record) |
+
+**Examples:**
+
+```html
+<script>
+var appConfig = {~DJ:AppData.Config~};
+var currentRecord = {~DJ:~};
+</script>
+```
+
+```javascript
+_Pict.AppData.Config = { theme: 'dark', language: 'en' };
+_Pict.parseTemplate('{~DJ:AppData.Config~}');
+// '{"theme":"dark","language":"en"}'
+
+_Pict.parseTemplate('{~DJ:~}', { id: 1, name: 'Test' });
+// '{"id":1,"name":"Test"}'
+```
+
+Useful for passing data from templates into JavaScript contexts, data attributes, or API payloads.
+
+---
+
+## DataEncodeJavascriptString (DEJS)
+
+Resolves a value and escapes it for safe use inside a JavaScript string literal. Escapes quotes, backslashes, and other characters that would break a JS string.
+
+**Tags:** `{~DataEncodeJavascriptString:ADDRESS~}` `{~DEJS:ADDRESS~}`
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| ADDRESS | Dot-notation path to resolve |
+
+**Examples:**
+
+```html
+<script>
+var userName = "{~DEJS:AppData.User.Name~}";
+var description = "{~DEJS:Record.Description~}";
+</script>
+```
+
+```javascript
+_Pict.parseTemplate('"{~DEJS:Record.Quote~}"',
+	{ Quote: 'She said "hello" and left.' });
+// '"She said \"hello\" and left."'
+```
+
+Always use DEJS when embedding data values inside JavaScript string literals in templates. Using plain `{~D:...~}` inside a quoted string risks injection if the data contains quotes or special characters.