CDIN Runtime

The Lua layer that coordinates editor behavior in CDIN.

CDIN Runtime contains the editor behavior: commands, key bindings, views, settings, workspace state and extensions. It is written in Lua and is designed to work with the other parts of CDIN rather than replace them.

What is Runtime?

When a user presses a key or runs a command, Runtime decides what should happen next. It coordinates editor features and describes the logical UI state. It delegates document operations to the Host instead of keeping a second, independent copy of document text.

The parts of CDIN have separate responsibilities:

Part	Responsibility
Frontend	Displays the editor and forwards user input.
Runtime	Coordinates commands, key bindings, views, settings and extensions.
Backend	Provides Runtime with access to Kernel and operating-system services.
Kernel	Owns document content, edits, versions and undo/redo history.

The separation is intentional: Runtime does not draw the window, perform pixel-level layout, or directly own the document's permanent contents.

Current status

This repository contains the Runtime policy layer and its Lua-side Backend boundary (0.4.1). It targets the stable Host API 1.0.0 and the shared Frontend Protocol 1.0.0, including version-pinned line-window reads and owner-thread Frontend event dispatch. It is not yet a complete, runnable CDIN editor or a Runtime 1.0.0 release: live Lua 5.4 + Kernel + Backend integration, legacy extension parity and a reviewed stable Host API are still required.

The CDIN specification is the source of truth for cross-project contracts. This README describes the current state of this repository; it does not override the specification.

Try it

You need Lua 5.4 and make. Clone the repository and run the tests:

git clone https://github.com/cdin-editor/runtime.git
cd runtime
make check

Run the static guards (no console output, no native code, no second logger) with make boundary. CI and releases run through m-mdy-m/pipeline; see Build and test.

Run one test group at a time when debugging:

make unit
make integration

The integration tests use a simulated Host. The companion Backend repository provides a live Lua 5.4 + Kernel integration workflow; passing simulated tests alone does not prove that production path. The default interpreter is lua5.4. If your installation exposes Lua 5.4 as lua, run make check LUA=lua.

For a first-time walkthrough, see the User Guide.

A small example

Runtime is created with a Host. The real CDIN Backend will provide it; this example uses the test Host so you can explore the current API without a running editor.

-- Run from the repository root with Lua 5.4.
package.path = "lua/?.lua;lua/?/init.lua;tests/?.lua;tests/?/init.lua;" .. package.path

local Runtime = require("cdin.runtime")
local FakeHost = require("support.fake_host")

local runtime = Runtime.new({ host = FakeHost.new() })
runtime:start()

local document = runtime:open_document("Hello, CDIN\n", {
  path = "hello.txt",
})
local view = runtime:create_view(document.id)

local text, info = document:read(0, document.length)
assert(text == "Hello, CDIN\n")
assert(info.version == document.version)

runtime:pump_notifications()
runtime:shutdown()

This example creates an in-memory document. It does not open a real file or display a window, and FakeHost is test support—not part of a production build.

What it provides

• Application startup and shutdown, shared errors and event notifications.
• Command registration and execution, input normalization and key bindings.
• Document clients and helpers that delegate document ownership to the Host/Kernel.
• Configuration, workspace state, views, selections and a logical pane tree.
• A semantic UI model, theme and style registries, and syntax highlighting.
• Extension registration, lifecycle management and a restricted extension sandbox.

Documentation

Guide	What it covers
User Guide	What Runtime does and how to run the current example.
Architecture	How Runtime fits into CDIN.
Runtime Host API	Services that the Backend must provide.
Extension API	Registering and managing Runtime extensions.
Runtime types	Shared data structures used by the API.
Errors and lifecycle	Error handling, startup and shutdown.
Build and test	Local development and test commands.
Changelog	Changes recorded for each version.
Spec traceability	Requirement-to-code mapping, evidence and 1.0.0 release gates.

CDIN ecosystem

Runtime is one part of CDIN. These repositories describe the neighboring projects:

Project	Role
CDIN	The editor application.
Kernel	The document and text engine.
Specification	Shared contracts between CDIN components.
cdin-x	Extensions and additional editor features.

Contributing

Bug reports and feature requests can be submitted through the YAML forms in .github/ISSUE_TEMPLATE/. Before opening a pull request, read CONTRIBUTING.md and run the relevant tests. Please keep changes aligned with the CDIN specification.

See also: Code of Conduct · Security · Code owners.

License

CDIN Runtime is licensed under GPL-3.0-or-later. See LICENSE and NOTICE.