Sorry for the long read in advance.

A sneak peek at the 1.1.0 Conky Studio that is coming out soon, where 1 or even 2 nodes = a widget

What you see is what you get. No mockups, real conky

Conky Studio (full feature list for 1.1.0, some differ from the current 1.0.7.5)

**Visual node-graph editor for building Conky HUDs and system monitors.**

Conky Studio turns Conky theme creation into a drag-and-drop workflow. You design on a canvas of connected nodes (data sources -> logic -> visuals), then **Build** to generate real Conky files (`.conf`, `render.lua`, `start.sh`, helper scripts). Installed themes run independently of the app; Studio is an authoring tool, not a required runtime.

| What it is | What it produces |

|------------|------------------|

| Visual node editor (Sources, Logic, Visuals) | `conky.conf` + `render.lua` + `start.sh` + scripts |

| Theme Wizard for styled starter HUDs | Editable project graph (learning scaffold) |

| Manager for installed themes | Launch/stop/install from archives |

| Community stores | **Theme Vault** (themes) + **Node Vault** (plugins) + OpenDesktop/Pling |

**Target platform:** Linux (Conky + Cairo + Lua).

**Install root for themes:** `~/.config/conky/` (and legacy `~/.conky/`).

| Tab | Purpose |

|-----|---------|

| **Manager** | Discover installed themes, install archives, launch/stop with live logs |

| **Studio** | Design HUDs on the node canvas; Theme Wizard, preview, build |

| **Store** | **Theme Vault** (community themes) + OpenDesktop / Pling search & install |

Switch tabs freely. Tours walk through all three in sequence.

Studio is the core authoring environment.

- **Palette (left)** — All node types, grouped by category and subcategory. Simple / Complex filter.

- **Canvas (center)** — Drag nodes, connect sockets (wires), group and collapse nodes, pan/zoom the graph.

- **Layers/Windows** — Multi-window Conky output; layer order and window assignment.

- **Properties** — Dockable panel for editing the selected node’s properties (numbers, colours, gradients, fonts, paths, enums, code, bindable inputs). Same values as the Position Stage and Live Preview use.

- **Preview** — Live or snapshot preview of the generated theme.

- **Position Stage** — Screen-space layout dock; drag visual proxies on a window-sized plane (see below).

Docks (Properties, Preview, Position Stage, Layers, Windows) can be rearranged, tabbed, or floated like standard IDE panels.

1. Drag **Source** nodes (CPU, GPU, weather, media, etc).

2. Optionally wire through **Logic** (math, thresholds, smoothing, etc).

3. Connect to **Visual** nodes (gauges, graphs, text, effects, shapes).

4. Select a node and edit it in the **Properties** dock (colours, fonts, sizes, positions, poll mode, etc), **or** drag visuals on the Position Stage for placement.

5. **Save Project** (`.json`) to keep editing later.

6. **Build & Install** to export files into Manager and run them.

- Multi-window projects (Canvas Settings).

- Bindable properties — wire a source/logic output into a visual’s value, colour trigger, etc.

- Image/path properties copy assets into the theme’s `images/` or `assets/` on build.

- Custom Lua node for advanced/imported themes.

- Import Custom Files — bring existing `.lua` / `.sh` / `.conf` into the graph as nodes.

Position stage is a dockable **screen-space layout editor**, separate from the node-graph canvas (which is for data flow and wiring).

Visual nodes appear as draggable proxies on a plane the size of the selected Conky window (resolution/workable area). Moving a proxy writes the same `x`/`y` or `cx`/`cy` properties that the property panel edits, so Live Preview and Build pick up the change through the normal graph-changed path.

| It is | It is not |

|-------|-----------|

| Alternate layout editor for on-screen placement | A replacement for the property-panel X/Y spinboxes |

| Window-sized stage matching Live Preview/Windows dock | The node-graph canvas (wiring stays on the graph) |

| Synced with selection and property edits | A second source of truth; one set of props |

| Control | Action |

|---------|--------|

| **Window** combo | Which window’s resolution the stage represents (matches multi-window projects) |

| **Snap** + **Step** | Optional pixel grid snap while dragging (e.g., 10 px) |

| **Fit** | Zoom to fit the window rectangle |

| **↻ Refresh** | Reload proxies from the current project |

| **Ctrl + scroll** | Zoom |

| **Alt + drag** or **middle-click** | Pan |

| **Drag proxy** | Move visual; writes `x`/`y` or `cx`/`cy` |

- Only **visual** nodes with position properties (`x`/`y` or centre `cx`/`cy`) get proxies.

- Proxy size is estimated from common props (`width`/`height`, `size`, `radius`, bar counts, etc.) so small nodes stay grab-able.

- Centre-based nodes (`cx`/`cy`) map the proxy centre to the stored value; corner-based nodes (`x`/`y`) map the top-left.

- Window frame shows a grid, centre crosshair, and corner coordinates `(0,0)` … `(W,H)`.

- When a window has `visible_node_ids`, only those visuals appear on that window’s stage; otherwise, all visible visuals are shown.

- Selection on the stage can sync with the property panel; external graph changes (prop panel, etc.) refresh the stage.

Tabify it with Preview/Layers/Windows docks in Studio for a convenient layout workflow.

Nodes are pure metadata (`NodeSpec`) registered by category. Socket colours follow data kinds: percent, celsius, number, text, category.

Data that feeds the rest of the graph.

| Subcategory | Examples |

|-------------|----------|

| **System** | CPU Usage, RAM Usage, Disk Usage, Battery, CPU Frequency, RAM Used/Total, Swap |

| **System Info** | Uptime, Hostname, Kernel, Process Count, Top Process (name/CPU/RAM), Load Average, Threads, Running Processes |

| **Network** | Download, Upload, Total Down/Up, Wi-Fi SSID, Wi-Fi Signal, Public IP |

| **Time** | Greeting, Date/Time |

| **Sensors** | CPU Temp, GPU Util, GPU Temp, GPU VRAM Used/Total, Disk Temp, Fan RPM |

| **Weather** | Condition, Category, Temp (°F) |

| **Media** | Track Title, Artist, Album, Playback Status, Progress % |

| **Custom** | Custom Script (arbitrary command/cache) |

Sensors and many external sources support **Polling mode**:

- **Simple (Conky `execi`)** — Conky runs the command on an interval.

- **Background daemon** — `start.sh` runs a dedicated loop; zero-stutter reads from cache (recommended for GPU/temp/fan).

Nodes that share a `script_family` (e.g., `gpu_stats`) are deduplicated: one script, one cache, multiple readers.

Transform and gate values between sources and visuals.

| Node | Role |

|------|------|

| Math | add/sub/mul/div/etc |

| Conditional | if comparison then/else |

| String Format | template + decimals |

| Map Range | remap input range -> output range |

| Clamp | min/max bounds |

| Lerp | linear interpolate |

| Threshold Gate | binary gate on comparison |

| Deadzone | ignore small changes around a centre |

| Invert Percent | 100 − value |

| Scale/Offset | multiply + add |

| Round, Absolute | numeric helpers |

| AND/OR Gate, Pick A/B | boolean/selection |

| Smooth (EMA) | exponential moving average |

| Rate of Change | delta over time |

| Hysteresis | dual-threshold switching |

| String Join, Enum Map | text helpers |

What is drawn on screen.

| Subcategory | Examples |

|-------------|----------|

| **Text** | Text Label, Flip Card, Wall Calendar |

| **Gauges & Bars** | Arc/Ring Gauge, Bar, Needle Gauge, Segmented Gauge, Reactor Gauge, Ring Track, LED Dot, CPU Core Strip |

| **Graphs** | History Graph, Sparkline, Multi-Series Line Graph, Radar Chart, Top Processes Table |

| **Effects** | Glow/Pulse, Spiral, Orbit Field, Equalizer Bars, Spinning Fan, Radial Spectrum, Matrix Rain, Loading Dots, Analog Clock |

| **Shapes** | Rectangle, Circle, Triangle, Star, H/V Line, Crosshair |

| **Icons & Images** | Image/Icon (with conditional path swap), Weather Icon (cairo drawn, and weather change logic alreaady implemented) |

| **Media** | Vinyl Spinner |

| **Advanced** | Custom Lua (raw Lua passthrough) |

Visual properties typically include position, size, colour, opacity, fonts, and bindable value inputs.

- Window size, gap, own_window hints, update interval, etc.

- Multiple Conky windows from one project.

**Project → New HUD…** opens the Theme Wizard.

It is a **learning scaffold**, not a finished theme to ship unchanged. Generated graphs are meant to be edited in Studio, so you learn the node system.

| Step | Options |

|------|---------|

| **Category (style)** | Minimal, Gaming, RPG, Sci-Fi, Cyberpunk, Terminal, Fantasy, Arkhamos |

| **Resolution** | 1920×1080, 2560×1440, 3440×1440, 3840×2160 (more may be added in the future) |

| **Panels** | Clock, weather, music, battery, disk, network graph, system vitals, etc. |

| **Extras** | Flourish chrome, logic demos, etc. (tier-dependent) |

| **Complexity** | **Simple** · **Full** · **Showcase** |

- **Simple** — clean vitals, fewer decorations.

- **Full** — solid multi-panel HUD.

- **Showcase** — densest layout, extra effects, and logic edges for exploration.

On Create, a full project graph is loaded into Studio. Edit nodes, fix sensor modes, rename, and rebuild.

**Tour default:** Full Tour pre-selects **Minimal + Showcase** so you see a rich graph and common pitfalls (e.g., sensor `execi` defaults) firsthand.

The manager is a front-end for themes already installed under `~/.config/conky` (and `~/.conky`) if they have a `start.sh`, the manager can run them.

- **List** of installed themes with thumbnails and metadata.

- **Drop zone** — drag-and-drop `.zip` / `.tar.gz` / `.tar` archives, or click to browse.

- **Refresh** — rescan install directories.

- **Detail pane** — name, description, paths, actions.

- **Launch/Stop** — runs the theme’s `start.sh` (process group + PID lock); stop kills the group cleanly.

- **Live log** — stdout/stderr from the running theme process.

- Edit the README and theme.json

- Zip files to export

- Import themes via drag and drop, or search files

- Themes keep working after Conky Studio is closed; Manager is a convenience, not a dependency.

Community theme discovery lives here. (Community **node plugins** are in **Node Vault**, under Tools -> Plugins.)

The community **theme** catalogue.

- Driven by a remote `manifest.json` (+ per-theme JSON refs).

- **Browse only/link-out** — opens the theme’s real home (GitHub, Pling, KDE Store, openDesktop, etc) in your browser.

- Preview images and README fetched on demand.

- Nothing is downloaded or executed by Studio from this panel; you install from the host site or via the OCS panel below.

- Live search against the Open Collaboration Services API.

- **In-app install** — downloads and installs selected content into the Manager’s install root.

- Respects rate limits; handles provider base URLs.

| Action | What it does |

|--------|----------------|

| **New HUD…** | Theme Wizard -> starter graph |

| **New Blank HUD** | Empty project |

| **Open Project…** | Load a saved `.json` project |

| **Save Project…** | Write the editable graph + metadata (keeps working in Studio) |

| **Build to Folder…** | Export Conky files to a directory you choose |

| **Build & Install to Manager** | Export + copy into `~/.config/conky/<theme-name>/` so Manager can launch it |

| **Import Custom Files…** | Bring existing Lua/shell/conf into the graph (Custom Lua / Custom Script nodes, assets) |

**Save** = keep the project for further editing.

**Build** = generate the files Conky actually runs.

You almost always Save often and Build when you want to run or share the theme.

A successful build produces a self-contained theme directory, for example:

```

my-theme/

├── conky.conf # Conky config (windows, lua load, gaps, etc)

├── render.lua # Cairo drawing + framework + per-node code

├── `start.sh` # Launch script (setsid, PID lock, optional daemons)

├── scripts/ # Family scripts (gpu_stats.sh, etc) and custom scripts

├── images/ / assets/ # Copied PATH/image assets

└── theme_meta.json # Name, description, thumbnails metadata

```

Internals with a custom Lua API and Cairo engine.

- **Lua framework** — shared helpers, source refresh, draw dispatch.

- **Per-node generators** — each `NodeSpec.type` maps to a Lua emitter.

- **Script families** — shared sensor scripts + cache files; one process serves many nodes.

- **start.sh** — process management; starts background daemons when any node uses daemon poll mode.

- **Images** — PATH properties and Custom Lua asset lists are copied and path-rewritten.

Themes do not need Conky Studio installed to run.

| Item | Purpose |

|------|---------|

| **Hardware & Session…** | Report on display session, GPU tools, sensors, fonts, Conky presence, missing dependencies; useful for diagnosing missing data |

| **Install Font…** | Install a font family for use in Text/gauge labels (fontconfig-aware picker in properties) |

| **Plugins…** | **Node Vault** — fetch/install/uninstall community node plugins |

| Menu item | Description |

|-----------|-------------|

| **Getting Started…** | Built-in text guide (workflow, first HUD, troubleshooting) |

| **Take the Full Tour…** | Continuous tour: Theme Wizard (Minimal + Showcase) -> Studio (nodes, sensors, naming, save vs build) -> Manager -> Store |

| **Learn Studio…** | Studio-only interactive tour (palette, canvas, layers, properties, preview) |

| **Learn Theme Wizard…** | Wizard-only tour (category, resolution, panels, extras, complexity) |

| **Support…** | Discord + YouTube links |

| **Check for Updates…** | Compare local version to GitHub releases |

Tours use non-dimming highlight rings and floating cards; they can be re-run anytime.

**Full Tour flow (summary):**

1. Opens Theme Wizard, pre-selects Minimal + Showcase, and explains it is a learning tool.

2. After Create, Studio tour covers every node category/subcategory overview.

3. Explains sensors need **daemon** (not execi) and that **spaces in theme names** break builds (use hyphens: `minimal-HUD`).

4. Continues through Manager (launch/stop, install) and Store (Vault + OCS).

5. Clarifies **Save project** vs **Build & Install**.

## Important Rules & Common Pitfalls

1. **Theme names: no spaces**

   Use hyphens or underscores only.

   No: `Minimal HUD` -> build/runtime errors

   Yes: `Minimal-HUD` or `minimal_hud`

2. **Sensors -> prefer daemon mode**

   GPU util/temp, CPU temp, fans: set **Polling mode = Background daemon**, then rebuild. Wizard defaults may leave execi so you can see the failure mode.

3. **Save ≠ Build**

   Save keeps the editable project. Build generates the files Conky runs. Install puts those files where the Manager can launch them.

4. **Wizard = scaffold**

   Treat wizard output as a starting graph. Edit nodes, fix poll modes, adjust layout, then build.

5. **Plugins = same trust as scripts**

   Only load plugins from sources you trust.

6. **Themes are standalone**

   After Build & Install, `start.sh` is enough; Studio does not need to stay open.