Salamatrix Extension Framework

One framework, several ways to extend Salamander

Salamatrix keeps the useful simplicity of Automation while adding the pieces needed for real, long-lived extensions. The public surface is service-oriented and versioned, so providers can evolve through append-only contracts instead of coupling every extension to Salamander internals.

The Salamatrix service catalog

Services are discovered through the host registry by a stable identifier and version. The framework can expose the same capability to C++, Automation and runtime workers without making runtime providers dependencies of Automation.

From script to extension

A simple script can remain simple. A manifest-backed extension opts into identity, capabilities, lifecycle and services only when it needs them.

{
  "schema": 1,
  "id": "example.folder-watcher",
  "name": "Folder Watcher",
  "version": "1.0.0",
  "runtime": "Lua",
  "entryPoint": "main.lua",
  "capabilities": ["panels.read", "events", "storage"],
  "commands": [{
    "id": "example.folder-watcher.open",
    "title": "Folder Watcher...",
    "handler": "open",
    "menu": "both",
    "toolbar": true
  }]
}

Native menu and toolbar integration

Every declared command can contribute to the Plugins menu, panel context menus and the dedicated, configurable Extension Bar. Multi-command packages are grouped under their localized package name, toolbar buttons can open package-local command menus, and command-specific light/dark SVG icons follow Salamander's theme and DPI.

Plugin Manager shows ordinary plugins and manifest extensions together. Users can activate or deactivate an extension, edit its declared settings, and inspect runtime or dependency status. The Samandarin Plugin Updates window installs catalog packages together with their required plugin dependencies.

Design boundary: Salamatrix is not intended to replace the complete native Plugin SDK. Native plugins remain the right choice for deep integration, maximum performance and ownership of complex UI.

Standalone runtime providers

Runtime providers are optional .SPL plugins. The user installs the interpreter separately; the provider discovers it, owns the worker bootstrap and registers its runtime with the Salamatrix broker.

The five workers share the same dialog surface, command state, typed storage contract, event bridge, host language lookup and SMX1 transport. Python, PowerShell, PHP and Node are discovered from explicit environment overrides or the system path. The Lua provider ships a compatible interpreter, while still allowing an explicit override. Workers can add native folder and file pickers, for example:

dialog.add_folder_picker("root", "C:\\")
commands.register("watch", "Watch folder")

await dialog.addFolderPicker("root", "C:\\")
commands.setState("watch", true, true)

Lua extensions use the same snake-case facade as Python, including dialog.add_folder_picker, commands.register, storage.keys and ui.notify.

Operational note: Runtime providers borrow the framework broker but do not own it. Shutdown validates the broker identity before unregistering adapters, preventing stale-broker calls during unload.

Bundled extensions

All three packages include localized metadata and UI resources for the languages shipped by Samandarin.

Salamatrix AI (experimental)

SalamatrixAI.SPL is a separate native provider and the sole owner of the local assistant workflow. It can use the same service registry and focused events without making AI or Automation a prerequisite for the runtime providers.

The assistant supports provider selection, structured generation, capability and effect validation, preview, run and save/package flows. The optional Salamatrix AI Local LLaMA.SPL companion runs a server-free llama.cpp and Qwen coder model; its CPU runtime and model assets are installed on demand instead of being bundled with the main installer.

Current status

Salamatrix is an evolving MVP with a working platform foundation. The implementation and GAP analysis are intentionally explicit about what is already wired and what remains to mature.

Technical documentation

• Salamatrix.UI framework guideNative control catalog, lifecycle, layout/options, dark mode and DPI, plus working examples in Node, Python, PowerShell, PHP, Lua, Automation JScript and C++.
• Salamatrix Automation API referenceDocumentation for the API: what is implemented by the current Salamatrix Framework and exposed to scripted extensions.
• Salamatrix Platform FoundationService names, versioning, registry, APIs, UI, worker transport and acceptance criteria.
• Standalone Salamatrix runtime providersProvider lifecycle, package split, worker UI, events, commands, storage and shutdown safety.
• Salamatrix runtime provider developmentGuidelines and best practices for developing standalone runtime providers in your preferred language.
• Salamatrix framework GAP analysisRequirement matrix, verification snapshot, implementation evidence, risks and recommended phases.

License

Salamatrix Framework and official extensions are open-source software licensed under GPLv2 or later. Some individual files and libraries may use different but compatible licenses.