Define Lua config architecture

[inayayousfi]

Written by inayayousfi, typed by gpt-5.6-sol running in OpenCode.
Every call here is inayayousfi's, and no agent acted on its own.

Goal

Add Lua configuration without creating a second runtime model. Lua should produce the same native config, behavior, event, action, and state shapes used by bundled Python config today.

Python remains responsible for validation, window and component construction, queue dispatch, state ownership, backend adapters, and process lifecycle. Concrete layouts and user policy should move to Lua.

Existing Runtime Contract

The Lua layer must compile into these existing boundaries:

• Visual config describes labels, display variants, geometry, component kinds, and stable IDs. It contains no backend output or runtime policy.
• Root BehaviorBinding records attach behavior to exact SourcePath targets.
• Every interactive key and generic button has exactly one binding. Missing, duplicate, unresolved, extra, and unknown bindings fail before windows are built.
• Components emit component.pressed and component.released, then render complete snapshots from the central state store.
• Events report what happened. Actions request effects. Both use lowercase dot-separated names and native Lua/Python data only.
• Queue messages never contain Qt objects, backend objects, Python callbacks, Lua functions, or dataclass instances.
• The keyboard service owns backend lifecycle, output registration, observations, and press handles. Keyboard policy stays in behavior handlers.
• Durable state is addressed by full app, profile, window, surface, layout, grid, and component paths.

Lua Config Loading

The loader should search the standard per-user config location:

Unix: $XDG_CONFIG_HOME/axidev-osk/config.lua
Unix: ~/.config/axidev-osk/config.lua
Windows: %APPDATA%/axidev-osk/config.lua

If no user config exists, load the bundled default. If user config fails to load or validate, show the error and start with the bundled recovery config.

A Lua root config may define multiple profiles. One profile is active at a time. The active profile compiles into runtime windows, surfaces, layouts, components, and behavior bindings. Reusing a layout must create fresh runtime state for each instance.

Lua Behaviors And Hooks

Lua-defined behavior and hook names register through the same behavior registry as built-ins. Each registration supplies an argument decoder and a Lua callback reference. The queue stores the reference and native arguments, never the function itself.

Callbacks are deferred by default. A blocking before-hook may cancel or replace default behavior. All matching before-hooks run, ordered side messages are preserved, and the last cancel or replace decision wins. After-hooks may add messages but cannot undo effects that already ran.

A callback failure produces behavior.failed. Lua callbacks must not mutate widgets, backend objects, or durable state directly. They return events or actions to the queue.

State And Reload

The main runtime owns durable state. Lua can read snapshots and request state changes through actions.

Config reload, profile switch, restart, and state reset must release active backend handles, remove old behavior bindings and handlers, discard non-preserved state, rebuild fresh layout instances, and leave the runtime usable when one step fails.

Preserved state needs an explicit config policy. Widget lifetime and Lua closure lifetime must never decide persistence.

Bundled Config

The bundled US ISO keyboard should become an ordinary Lua config loaded through the same path as user config. Its current visual geometry, stable component IDs, output behavior, modifier modes, display variants, prompt actions, and Ghost action form the parity target.

Python should not contain US ISO-specific layout knowledge after parity is established.

Acceptance Criteria

• A Lua root config can define profiles, windows, surfaces, layouts, components, and behavior bindings.
• User and bundled config use one loading and validation path.
• Invalid user config visibly falls back to a bundled recovery config.
• Lua-defined behavior and hook arguments receive runtime validation.
• Lua callbacks communicate only through events and actions.
• Blocking hooks can cancel or replace default behavior with deterministic ordering.
• Durable state remains in the main runtime store.
• Reload and profile switch clean up old handlers, backend handles, bindings, windows, and non-preserved state.
• Two uses of one layout receive independent runtime state.
• Bundled Lua US ISO passes parity tests without Python layout-specific behavior.

[inayayousfi]

Follow-up architecture refinements from further discussion:

Async User APIs Without Exposing Threads

The Lua API should not expose raw thread selection or make users manage task/executor objects. Users should express async intent through normal operations and simple options. The runtime decides the correct execution lane internally.

Good user-facing shape:

ctx.shell.run("detect-session", {
  async = true,
  tag = "startup-detect-session",

  on_success = function(ctx, result)
    ctx.state.set("session.info", result.stdout)
  end,

  on_error = function(ctx, err)
    ctx.log.warn("session detect failed", err.message)
  end,
})

Timer/delayed work should be similarly simple:

ctx.after(500, function(ctx)
  ctx.keyboard.tap("A")
end, {
  tag = "delayed-a",
})

The user-facing concept is:

do this async
tag it so it can be cancelled/replaced
run this callback when done

Not:

choose a thread
create an executor
manage a task object lifecycle

Internally, these operations still become events/commands flowing through the runtime queue. The runtime maps command types to safe execution lanes such as UI, main/runtime, Lua actor, IO/background, timer, or backend-safe execution.

Queue Items Should Stay Data-First

The public queue model should remain data-first, not arbitrary function-first.

Preferred model:

event: component.press
payload: { component_id = "...", button = "left" }
runtime routes to Lua callback handle
Lua returns command: keyboard.down
payload: { key = "A" }

Avoid making the queue itself primarily store opaque function pointers. Handler functions can exist behind dispatchers, but queued events/commands should be inspectable, loggable, cancellable, and eventually replayable.

Local Ephemeral State Exception

The queue/state-store rule applies to durable user-visible behavior and cross-subsystem coordination. Ephemeral implementation details may remain local inside a subsystem.

State should go through the queue/main state store if it affects:

• user-visible app behavior
• config behavior
• backend output
• profile/window/layout/component lifecycle
• persistence
• cancellation
• replay/debugging
• cross-subsystem coordination

State may remain local if it is purely ephemeral and cannot affect durable behavior outside one subsystem, such as:

• Qt hover/focus/paint internals
• temporary render polish state
• Lua garbage collector internals
• local stack variables during one callback

Qt Styling Through Lua

Lua config must expose Qt styling. This is important for user customization/ricing.

Use QSS directly instead of inventing a large custom styling DSL in v1.

Global theme example:

return osk.config({
  theme = {
    name = "transparent-terminal",

    qss = [[
      QWidget#rootSurface {
        background: rgba(12, 12, 18, 180);
        border: 1px solid #7aa2f7;
        border-radius: 14px;
      }

      QPushButton[componentType="key"] {
        color: #c0caf5;
        background: #1a1b26;
        border: 1px solid #414868;
        border-radius: 8px;
        padding: 8px;
      }

      QPushButton[interactionState="pressed"] {
        background: #7aa2f7;
        color: #1a1b26;
      }

      QPushButton[latched="true"] {
        border-color: #bb9af7;
        color: #bb9af7;
      }
    ]],
  },
})

Styling should be layered where practical:

global theme QSS
profile theme overrides
window/surface QSS
layout/grid object names/classes/properties
component object names/classes/properties
runtime dynamic properties for state

Component-level hooks example:

osk.key("Esc", {
  row = 0,
  column = U(0),
  io_key = "Escape",

  style = {
    object_name = "escapeKey",
    classes = { "danger", "function-key" },
    properties = {
      accent = "red",
    },
  },
})

The runtime should set useful Qt dynamic properties so QSS can target state and identity:

componentType="key"
keyId="shift"
ioKey="ShiftLeft"
interactionState="latched"
latched="true"
pressed="true"
profile="default"
layout="us_iso"

Example:

QPushButton[keyId="shift"][latched="true"] {
  background: #bb9af7;
}

Window-Level Visual Options

Lua window config should expose simple visual/window options such as opacity, in addition to overlay behavior.

Example:

osk.window("keyboard", {
  title = "axidev on-screen keyboard",

  opacity = 0.92,

  overlay = {
    enabled = true,
    always_on_top = true,
    placement = "center",
    screen_margin = 16,
    custom_chrome = true,
  },

  style = {
    object_name = "mainKeyboardWindow",
    qss = [[
      QWidget#rootSurface {
        background: rgba(12, 12, 18, 190);
      }
    ]],
  },

  layouts = {
    osk.use_layout("us_iso"),
  },
})