Salamatrix Extension Framework

Open Salamander platform foundation

Extensions that feel native, whatever the language.

Salamatrix is the new extension layer between a one-shot Automation script and a full native C++ plugin. It gives extensions a stable service model, a manifest, lifecycle, events, persistent state and a common way to work with Salamander panels.

Native plugins and out-of-process workers can use the same concepts. A Python, PowerShell, PHP or Node extension does not need to reinvent the host integration for every runtime.

Explore the framework Read the platform specification

ExtensionsNative · Automation · Workers

↕

Salamatrix servicesUI · Commands · Events · Storage

↕

Open SalamanderHost, panels and Plugin Manager

SMX1
versioned

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.

Native foundation

SALAMATRIX.SPL is the framework provider. It registers the shared service registry, host adapters and the common object model used by native and scripted callers.

Common object model

Extensions can reason about Salamander.Sides, Tabs, Commands, File Operations, Dialogs, Events and Storage in a consistent way across languages.

Process boundary when useful

The SMX1 worker protocol provides a bounded JSON line transport with typed messages, request IDs, events, shutdown and error handling.

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.

◫

Sides & tabs

Salamatrix.Sides exposes snapshots of the left and right sides, their active tabs, paths and selection context. It is the foundation for extensions that inspect or react to the current workspace.

⌘

Commands & file operations

Salamatrix.Commands maps public names such as QuickRename, Copy and Move to existing Salamander command handlers. FileOperations adds interactive copy, move, rename, delete, folder creation, refresh and properties operations.

◉

Events

Salamatrix.Events provides versioned subscriptions with safe unsubscribe handles. Extensions can receive host notifications and tab lifecycle events through the same event names, including worker-runtime bridges.

▣

Persistent storage

Salamatrix.Storage gives every manifest extension its own validated namespace for typed values and keys. State survives reloads without falling back to one unsafe global script namespace.

▤

UI and dialogs

Salamatrix.UI supplies shared dialog primitives and progress UI. Runtime workers can add controls, validation, events, file pickers and folder pickers while Salamander owns the actual native window.

⇄

Runtime broker

Salamatrix.Runtime is the broker between the framework and optional interpreter providers. It keeps Python, PowerShell, PHP and Node integration modular and discoverable.

◇

Extensions registry

Salamatrix.Extensions tracks manifest-backed extensions, activation state, capabilities and lifecycle callbacks. It gives the Plugin Manager a stable host-side view of installed extensions.

⚙

Automation adapter

The Automation adapter exposes the same modern services through a script-shaped Salamander object. Existing one-shot scripts remain useful while manifest extensions gain lifecycle and persistent state.

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.

01DiscoverPlugin Manager finds the manifest and checks its runtime and minimum framework version.

02ActivateThe framework validates capabilities, registers commands and starts the selected entry point.

03RunThe extension uses shared services, receives events and keeps its own persistent state.

04ReleaseSubscriptions, worker sessions and provider registrations are removed safely and predictably.

{
  "id": "example.folder-watcher",
  "runtime": "python",
  "entry": "main.py",
  "minimumFramework": "1.0",
  "capabilities": ["events", "storage", "commands"]
}

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.

PythonRuntime.SPLCPython worker and Python API

PowerShellRuntime.SPLPowerShell worker and cmdlet-shaped API

PHPRuntime.SPLPHP CLI worker and PHP API

JavaScriptRuntime.SPLNode worker and asynchronous API

The four workers share the same dialog surface, command state, storage contract, event bridge and SMX1 transport. They 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)

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.

Salamatrix AI

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.

Use local AI model based on LLaMA and Qwen2.5-Coder 0.5B Instruct GGUF Q4_K_M model or connect to a remote AI service for automated tasks, scripts and extensions development.

AI-ready by design

Ask · Preview · Run · Save

The framework exposes machine-readable service and API descriptions so an assistant can propose an extension action, show the user what will happen, run it through the same command and file-operation paths, and persist the useful result.

Ask→Preview→Run→Save

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.

ImplementedService registry, versioned contracts, Plugin Manager integration, manifests, lifecycle registry, storage, events, Sides, UI, Commands and FileOperations.

ImplementedStandalone Python, PowerShell, PHP and Node providers with shared worker protocol and FolderPicker support.

Next layersBroader UI coverage, richer worker event dispatch, capability policy, packaging/distribution polish and continued compatibility testing.

Guiding ruleExtend contracts append-only, preserve legacy Automation, and keep runtime providers independent from Automation dependencies.

Technical documentation

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 framework GAP analysisRequirement matrix, verification snapshot, implementation evidence, risks and recommended phases.

License

Open Salamander is open-source software licensed under GPLv2 or later. Some individual files and libraries use different but compatible licenses.