Lua domain model

Domain Model of MC Lua Extensions

1. Architectural Overview (Principles)

The architecture is based on a strict separation of responsibilities between policy (Lua) and mechanism (MC Core).

• Single Runtime: Lua in MC is one subsystem, not a collection of separate plugins. It loads packages, isolates them from MC internals, and exposes several independent domain APIs.
• Architectural boundary:
  1. Lua package: Defines behavior, transformations, and content.
  2. Runtime adapter: Validates Lua values and translates them into the stable C ABI.
  3. Host services: Perform the permitted MC operations.
  4. MC Core: Owns widgets, memory, lifecycle, and rendering.
• Zero direct access rule: Lua never receives direct pointers to internal MC structures (WPanel, WEdit, buffers, widget IDs, VFS objects, and so on). All interaction goes through opaque handles and immutable snapshots.

Layer diagram

flowchart TD
    %% Nodes
    P["1. Lua Package"]
    RA["2. Lua Runtime Adapter / mc-lua"]
    HS["3. MC Host Services"]
    MC_W["Core: Editor, Panels, Viewer, Diff Viewer"]
    MC_M["Core: Dialogs, Processes, Keymap, Events, Lifecycle"]

    %% Edges
    P <-->|"Domain API calls and Lua callbacks"| RA
    RA <-->|"Validated, typed runtime ABI"| HS
    HS <-->|"Host operations and callbacks"| MC_W
    HS <-->|"Host operations and events"| MC_M

Loading

The arrows are bidirectional: Lua invokes host services through the runtime adapter, while MC delivers events, actions, and synchronous provider callbacks through the same ABI. This does not give Lua direct access to core subsystems.

---

2. Fundamental Technical Concepts

These entities span all API domains and provide stability and safety.

• Runtime: The loaded language engine (mc-lua). It is registered once and creates isolated Lua environments for packages.
• Capability: A named ability of the host to perform a class of operations. Availability depends on the build, host support, ABI size, runtime support, workspace, and active context. The current package manifest is not a permission-granting system.
• Context: A short-lived context of an active MC invocation. It determines which objects and mutations are available here and now. The context itself cannot be used outside the callback. A handle may be retained between callbacks when permitted by the lifecycle of its domain object, but host operations through it may only be invoked in an allowed active context.
• Opaque handle: A protected reference ({kind, id, generation}) to a host-owned object. It does not expose a memory address. When the object is closed, the handle becomes invalid, operations return closed, and the reference can never become valid again accidentally.
• Snapshot & Revision: An immutable description of object state at a particular revision. Operations using stale coordinates fail with stale_revision without modifying data.
• Error Model: Stable machine-readable codes (not_supported, closed, stale_revision, provider_busy) and separate diagnostic text cross the ABI boundary. Lua callback errors are isolated and must not crash MC.
• Source: An abstract description of where data comes from (bytes, a local file, a process, or a pipeline). The host materializes the source and passes it to the consumer.

---

3. API Domain Hierarchy (Functional Groups)

The APIs are separated by domain. A workspace determines the package's area of application and available context, but it is not synonymous with an API domain.

3.1. Package Management (Package Model)

Entities that describe the extension's own lifecycle.

1. Package: A unit of loading. It has an ID, name, workspace, entry point, enabled/disabled state, and a provides declaration.
2. Package Descriptor: A declarative package description (metadata), validated before Lua code is executed. The current manifest has neither a separate “package class” field nor a list of requested host capabilities.
3. Workspace: The area of application (file manager, editor, viewer, or terminal). It determines the context.
4. Package Origin & Precedence: A system or user directory. A package from the higher-priority origin shadows a package with the same ID from a lower-priority origin.
5. Indicator: A named fragment of persistent UI state owned by a package.

3.2. Editor Domain (mc.editor)

Operations on an open text document. MC owns the document; Lua receives its snapshots.

• Editor Document: A host-owned document identified by a handle.
• Document Info Snapshot: Document state (path, readonly, modified, revision).
• Position & Range: Buffer coordinates tied to a revision.
• Selection: A selection snapshot (mode plus one or more ranges).
• Edit & Transaction:
  • Edit: A declarative replacement of text in a range.
  • Transaction: An atomic set of edits that creates one undo entry.

3.3. Panel Domain (mc.panel & mc.panel_provider)

This domain distinguishes automation of existing panels from providers of virtual namespaces.

Basic management (existing panels)

• Panel & Panel Reference: A temporary reference to an existing active or passive MC panel. It does not grant ownership of the widget.

Providers (virtual namespaces)

• Panel Provider: A global registration of a logical namespace (for example, git:, arc:, or ftp:). It defines capabilities, callbacks, and actions.
• Connection: A saved description of a provider entry point, such as a particular URL.
• Provider Instance: The state of one provider opening in one panel. It lives until the panel is closed.
• Panel View: A revisioned snapshot of the current panel state (entries, columns, focus), replaced as a whole after refresh.
• Panel Entry: An element of a view (a snapshot, not a file). It may be directory-like for navigation or file-like for content. The provider uses IDs consistently within an instance, and operations on an entry are additionally tied to the current view revision.
• Column & Presentation: A semantic entry field and its presentation rules; the host decides how it is rendered.
• Panel Selection: A snapshot of the current entry and marked IDs, passed to an action by value.
• Content Contract: The link between a panel entry and a content consumer. The Lua open_read() callback returns a typed source (bytes, local file, process, or pipeline), and the runtime bridge converts it to the common mc_pp_input_stream_t when necessary. This lets a standard consumer such as arcmc read through the stream API, while Lua does not implement the low-level open/read/close callbacks itself.

3.4. Viewer Domain (mc.ui — Viewer)

Displaying data in MC's native viewer.

• Viewer Source Definition: A global description of a source family (identity, callbacks, and help).
• Viewer Session: Controller state from create until close.
• Viewer Controller: An opaque object that connects a session to a host viewer.
• Viewer Source Specification: A prepared immutable source snapshot for opening in the viewer.

3.5. Shared UI Facilities (mc.ui — Dialogs, Alerts)

Shared host-owned user-interface elements.

• Dialog Specification: A declarative modal-dialog description. Lua does not manipulate widgets directly.
• Dialog Control: A typed form element (layout container, label, input, checkbox, radio/select, button, or separator).
• Dialog Result: The immutable result of a completed dialog.
• Help Reference: A reference to package-owned help content.

3.6. External Processes (mc.process)

Controlled execution of system commands.

• Process Request: The current mc.process.run() accepts a shell command string and a max_output limit. Structured argv, a working directory, and pipelines belong to typed process sources in the viewer-source ABI.
• Process Result: Process completion data (stdout, stderr, exit status, and truncation flags).
• Pipeline Source: A composition of process sources.

3.7. Events (mc.on)

A mechanism for subscribing to MC activity.

• Subscription: A package registration for an event.
• Event Snapshot: An immutable snapshot of event data. It does not provide access to a live widget.

---

4. Control Flow and Lifecycle (Key Bindings Flow)

The following sequence illustrates the domain model in operation.

1. The user presses a key in MC.
2. The global keymap translates it into an MC Command, for example CK_EditNew.
3. The panel plugin receives the command through handle_key().
4. The Runtime Adapter translates the invocation into a Domain Operation, for example by calling the provider's Lua callback new_connection().
5. The Lua package performs its logic and returns the result defined for that operation.

Example:

Shift-F4 → CK_EditNew → runtime adapter → calls provider's Lua function `new_connection()`
F4       → CK_Edit    → runtime adapter → calls `edit_connection(snapshot)`

---