LUDASH / MODULES

Your shell, one block at a time.

Resize a panel, change its corners, move it to the bottom—or replace a specific component with your own QML. Start with JSON, then add code when you need it.

Nine independent blocks

panel, wallpaper, launcher, overview, settings, setup, session, feedback and compatibility each have a style and an optional custom entrypoint. Settings, setup and feedback cannot be disabled, so recovery remains available.

Try a panel style

This playground only changes the website preview. Copy its JSON into Settings → Shell modules, validate it, then save to apply it in LunaDash. A partial document resets omitted fields to defaults.

Width 1200 pxHeight 48 pxCorner radius 18 pxPanel color

Generated module JSON

The style contract

Field	Accepted values
`schemaVersion`	Exactly 1. Documents are limited to 16 KiB.
`enabled`	Boolean; recovery blocks cannot be disabled.
`width / height`	0 means built-in size. Width 320–3840 (settings minimum 800). Panel height 24–96; settings/setup 480–2160; other heights 80–2160. Sizes clamp to the screen.
`margin / radius`	Integers from 0 to 64 logical pixels.
`background / foreground / accent`	inherit, #RRGGBB, or Qt #AARRGGBB. Inherit follows the desktop palette.
`fontSize`	10–28. Applies to panel labels and is passed to custom components.
`edge`	top or bottom for panel; top for other blocks. Panel height and margins reserve tiling space.
`custom`	Boolean enabled plus relative entry, such as panel/Main.qml.

The JSON file lives in ~/.config/LuDash/shell-modules.json, respecting XDG_CONFIG_HOME. Invalid external edits retain the last valid document. Module colors affect the main built-in surface and direct labels; shared nested controls retain the desktop theme.

Make the component yours

In Shell modules, create a panel or dashboard template. Existing code is never overwritten.
Edit ~/.config/LuDash/modules/panel/Main.qml in your editor.
Set custom.entry to panel/Main.qml and custom.enabled to true in JSON.
Review the code and imports, then explicitly allow custom code in Settings.

MAIN.QML / MINIMAL COMPONENT

import QtQuick
Item {
    id: root
    required property var shell
    required property var style
    required property string moduleId
    Rectangle {
        anchors.fill: parent
        color: root.style.background
        radius: root.style.radius
    }
    Text {
        anchors.centerIn: parent
        text: root.shell.focusedTitle
        color: root.style.accent
        font.pixelSize: root.style.fontSize
    }
}

The root must be an Item with required shell, style and moduleId properties. Use anchors and layouts; the host owns the Wayland window, dimensions and animations. Do not create another PanelWindow or ShellRoot. The entrypoint must resolve inside the module directory, match module/Main.qml using letters, digits, underscores or hyphens, and be at most 256 KiB.

Entry file edits trigger reload. For helper files, use explicit QML type registration where needed and touch the entrypoint after editing a dependency. Read state as a snapshot; use shell.command() or shell.setAppearance() for changes.

Custom QML is executable, trusted code. It can access files, processes and the network with your user permissions. Syntax/load errors fall back to built-in content; runtime hangs, crashes or malicious code cannot be isolated inside the same shell process.

Always keep a way back

TERMINAL

ludashctl module-code-trust false
ludashctl module-reset
ludashctl open-settings modules

Reset restores built-ins, disables custom code and preserves your QML files. If the shell is hung, disable code through the compositor's IPC and restart the session. Offline, remove the modules/allowCustomCode setting and rename the module JSON before restarting.