SLeeLa GUI Protocol™ — Guia™ 1.0
Protocol name: Guia™ Specification: SLeeLa GUI Protocol™ 1.1 Owner: MEARVK LLC Purpose: Language-neutral GUI-to-SLeeLa client/listener protocol.
1. Scope
Guia™ defines the names, objects, functions, states, events, transitions, bindings, and listener contract used when a GUI communicates with a SLeeLa client/runtime.
Architecture:
BODI/XML
│
▼
Guia™ protocol model
│
├── JavaFX adapter
├── Native GUI adapter
└── Other GUI adapters
│
▼
SLeeLa GUI Client
│
▼
SLeeLa Listener / Runtime / Circuit
BODI describes the interface. Guia™ defines its executable interaction contract. SLeeLa remains authoritative for application and circuit behavior.
2. Naming model
Every Guia™ object has a stable id, a type, an optional parent, and a lifecycle state.
Reserved object namespaces:
gui.*— application GUIwindow.*— windowsview.*— views/panelscontrol.*— interactive controlslayout.*— layout containersmenu.*— menus and menu itemsdialog.*— dialogsdata.*— models and bindingsevent.*— eventscommand.*— commandsclient.*— SLeeLa GUI clientlistener.*— listener endpointscircuit.*— SLeeLa circuitsmonitor.*— monitoring streamssession.*— GUI/client sessionserror.*— errorssecurity.*— authorization/security context
Names are case-sensitive. Implementations MUST NOT reuse an active object ID.
3. Core objects
3.1 GuiApplication
Represents the GUI process/application.
Fields:
idnameversionprotocolstatecapabilitiesclientId
3.2 GuiClient
Represents the SLeeLa-facing GUI client.
Fields:
idapplicationIdstatecircuitIdlistenerIdsessionIdcapabilities
3.3 GuiListener
Represents the event/message listener receiving SLeeLa events.
Fields:
idstateendpointprotocolVersionsubscriptionslastSequence
3.4 Circuit
Represents a loaded SLeeLa circuit.
Fields:
idpathnamestatepermissionsinputsoutputs
3.5 Session
Represents one GUI-to-client interaction session.
Fields:
idclientIdlistenerIdstatecreatedAtsequencesecurityContext
3.6 Control
Base GUI control.
Fields:
idtypeparentvisibleenabledvaluepropertiesbindings
Supported reference types include:
button, label, text, password, checkbox, radio, select, list, table, tree, slider, progress, image, canvas, web, audio, video, status, log.
3.7 DataModel
Represents GUI-visible application data.
Fields:
idschemavalueversionreadOnlysource
3.8 Command
Represents an operation callable by the GUI.
Fields:
idnameargumentspermissionstimeoutasyncstate
4. Visual vocabulary and components
Guia™ defines presentation components as part of the BODI/XML GUI vocabulary. Visual styling is declarative in BODI/XML and is interpreted by the GUI adapter.
4.1 Bevel
The bevel component creates a dimensional 2D edge or separator.
Attributes: id, orientation, style, size, light, shadow, and optional base.
Supported styles include raised, sunken, etched, flat, and adapter-compatible 2d-bevel.
4.2 2D gradient
The gradient component provides a two-dimensional visual surface transition.
Supported types are linear, radial, and bilinear. Linear gradients use direction, start, and end; bilinear gradients may use top-left, top-right, bottom-left, and bottom-right; radial gradients may use radius.
4.3 Style container
The style component groups reusable presentation declarations. A style-ref may apply a declared style to a compatible GUI component or container.
Visual styling MUST NOT change Guia™ object identity, lifecycle, security authority, or event semantics.
4.4 BODI/XML authority
For a named GUI setup, its base BODI/XML document is the authoritative declaration of GUI structure and visual styling. Adapter code SHOULD implement the declared structure rather than silently inventing a separate XML definition.
6. GUI functions
Lifecycle
GUI.INIT(application)
GUI.SHOW(gui)
GUI.HIDE(gui)
GUI.PAUSE(gui)
GUI.RESUME(gui)
GUI.UPDATE(gui)
GUI.CLOSE(gui)
GUI.DESTROY(gui)
Window/view functions
WINDOW.CREATE
WINDOW.SHOW
WINDOW.HIDE
WINDOW.FOCUS
WINDOW.RESIZE
WINDOW.MOVE
WINDOW.MINIMIZE
WINDOW.MAXIMIZE
WINDOW.RESTORE
WINDOW.CLOSE
VIEW.CREATE
VIEW.SHOW
VIEW.HIDE
VIEW.ACTIVATE
VIEW.DEACTIVATE
VIEW.DESTROY
Control functions
CONTROL.CREATE
CONTROL.DESTROY
CONTROL.SHOW
CONTROL.HIDE
CONTROL.ENABLE
CONTROL.DISABLE
CONTROL.FOCUS
CONTROL.BLUR
CONTROL.GET
CONTROL.SET
CONTROL.RESET
CONTROL.VALIDATE
CONTROL.REFRESH
Data functions
DATA.CREATE
DATA.GET
DATA.SET
DATA.UPDATE
DATA.DELETE
DATA.RESET
DATA.SUBSCRIBE
DATA.UNSUBSCRIBE
DATA.SNAPSHOT
DATA.COMMIT
DATA.ROLLBACK
Event functions
EVENT.BIND
EVENT.UNBIND
EVENT.EMIT
EVENT.CANCEL
EVENT.PAUSE
EVENT.RESUME
EVENT.SUBSCRIBE
EVENT.UNSUBSCRIBE
Command functions
COMMAND.REGISTER
COMMAND.UNREGISTER
COMMAND.ENABLE
COMMAND.DISABLE
COMMAND.INVOKE
COMMAND.CANCEL
COMMAND.STATUS
COMMAND.RESULT
COMMAND.ERROR
Client functions
CLIENT.CREATE
CLIENT.CONNECT
CLIENT.DISCONNECT
CLIENT.RECONNECT
CLIENT.PING
CLIENT.PONG
CLIENT.STATUS
CLIENT.CAPABILITIES
CLIENT.SHUTDOWN
Circuit functions
CIRCUIT.LOAD
CIRCUIT.UNLOAD
CIRCUIT.START
CIRCUIT.STOP
CIRCUIT.PAUSE
CIRCUIT.RESUME
CIRCUIT.RELOAD
CIRCUIT.STATUS
CIRCUIT.INPUT
CIRCUIT.OUTPUT
Listener functions
LISTENER.CREATE
LISTENER.START
LISTENER.STOP
LISTENER.PAUSE
LISTENER.RESUME
LISTENER.SUBSCRIBE
LISTENER.UNSUBSCRIBE
LISTENER.RECEIVE
LISTENER.ACK
LISTENER.NACK
LISTENER.RESET
LISTENER.DESTROY
Session functions
SESSION.CREATE
SESSION.OPEN
SESSION.AUTHENTICATE
SESSION.RENEW
SESSION.SUSPEND
SESSION.RESUME
SESSION.CLOSE
SESSION.EXPIRE
Monitoring functions
MONITOR.SUBSCRIBE
MONITOR.UNSUBSCRIBE
MONITOR.STATUS
MONITOR.METRIC
MONITOR.LOG
MONITOR.EVENT
MONITOR.ERROR
MONITOR.SNAPSHOT
5. Event names
Standard Guia™ events:
APP.START
APP.READY
APP.STOP
APP.ERROR
WINDOW.OPEN
WINDOW.ACTIVATE
WINDOW.DEACTIVATE
WINDOW.RESIZE
WINDOW.CLOSE
CONTROL.CREATED
CONTROL.CHANGED
CONTROL.FOCUSED
CONTROL.BLURRED
CONTROL.ENABLED
CONTROL.DISABLED
CONTROL.VALIDATED
CONTROL.ERROR
INPUT.CHANGED
INPUT.SUBMITTED
INPUT.CANCELLED
COMMAND.REQUESTED
COMMAND.STARTED
COMMAND.PROGRESS
COMMAND.COMPLETED
COMMAND.CANCELLED
COMMAND.FAILED
CLIENT.CONNECTING
CLIENT.CONNECTED
CLIENT.DISCONNECTED
CLIENT.RECONNECTING
CLIENT.READY
CLIENT.ERROR
CIRCUIT.LOADING
CIRCUIT.LOADED
CIRCUIT.STARTING
CIRCUIT.STARTED
CIRCUIT.PAUSED
CIRCUIT.RESUMED
CIRCUIT.STOPPING
CIRCUIT.STOPPED
CIRCUIT.FAILED
LISTENER.STARTING
LISTENER.READY
LISTENER.MESSAGE
LISTENER.ACKNOWLEDGED
LISTENER.REJECTED
LISTENER.STOPPING
LISTENER.STOPPED
LISTENER.ERROR
SESSION.OPENING
SESSION.OPEN
SESSION.AUTHENTICATING
SESSION.AUTHENTICATED
SESSION.SUSPENDED
SESSION.CLOSED
SESSION.EXPIRED
DATA.CREATED
DATA.CHANGED
DATA.COMMITTED
DATA.ROLLED_BACK
DATA.INVALID
MONITOR.STATUS
MONITOR.METRIC
MONITOR.LOG
MONITOR.ERROR
7. State machines
GUI
CREATED → INITIALIZING → READY → ACTIVE
ACTIVE → PAUSED → ACTIVE
ACTIVE → CLOSING → CLOSED
INITIALIZING → ERROR
ACTIVE → ERROR
Client
CREATED → CONNECTING → CONNECTED → READY
CONNECTING → FAILED
CONNECTED → DISCONNECTED
DISCONNECTED → RECONNECTING → CONNECTED
READY → SHUTTING_DOWN → CLOSED
Listener
CREATED → STARTING → READY → RECEIVING
RECEIVING → PAUSED → RECEIVING
RECEIVING → STOPPING → STOPPED
STARTING → ERROR
RECEIVING → ERROR
ERROR → RESETTING → STARTING
Session
CREATED → OPENING → OPEN → AUTHENTICATING → AUTHENTICATED
AUTHENTICATED → SUSPENDED → AUTHENTICATED
AUTHENTICATED → CLOSED
OPEN → EXPIRED
Circuit
UNLOADED → LOADING → LOADED → STARTING → RUNNING
RUNNING → PAUSING → PAUSED
PAUSED → RESUMING → RUNNING
RUNNING → STOPPING → STOPPED
LOADING → FAILED
STARTING → FAILED
RUNNING → FAILED
8. GUI-to-client listener transition
The normative client/listener startup sequence is:
GUI.CREATECLIENT.CREATELISTENER.CREATESESSION.CREATECLIENT.CONNECTLISTENER.STARTSESSION.OPENSESSION.AUTHENTICATEwhen requiredCIRCUIT.LOADCIRCUIT.STARTLISTENER.SUBSCRIBEGUI.SHOWAPP.READY
Runtime interaction then follows:
GUI action
↓
EVENT.EMIT
↓
COMMAND.REQUESTED
↓
COMMAND.INVOKE
↓
SLeeLa Client
↓
Circuit / Service
↓
LISTENER.RECEIVE
↓
LISTENER.ACK
↓
DATA.UPDATE / MONITOR.EVENT
↓
CONTROL.UPDATE
↓
GUI
9. Listener message envelope
A Guia™ listener message SHOULD contain:
protocol
version
messageId
sequence
timestamp
sessionId
clientId
listenerId
event
source
target
payload
status
error
sequence provides ordered delivery detection. messageId provides message identity. Implementations MAY provide transport-specific framing underneath this logical envelope.
10. Acknowledgement
Listeners use:
LISTENER.ACK(messageId, sequence)
LISTENER.NACK(messageId, sequence, reason)
ACK confirms receipt and acceptance of the message. NACK identifies a message that could not be accepted. A transport MAY separately provide delivery guarantees; Guia™ does not assume that every transport is reliable.
11. Binding model
Bindings connect GUI properties to SLeeLa data:
CONTROL → DATA
CONTROL ← DATA
CONTROL ↔ DATA
EVENT → COMMAND
COMMAND → DATA
DATA → EVENT
MONITOR → DATA
A binding MUST identify source, target, direction, conversion rules, and optional validation.
12. Error model
Standard categories:
GUI_ERROR
CLIENT_ERROR
LISTENER_ERROR
SESSION_ERROR
CIRCUIT_ERROR
COMMAND_ERROR
DATA_ERROR
AUTHORIZATION_ERROR
VALIDATION_ERROR
PROTOCOL_ERROR
TIMEOUT_ERROR
TRANSPORT_ERROR
Errors SHOULD contain:
code
message
source
operation
objectId
messageId
recoverable
details
13. Security boundary
Guia™ does not grant authority merely because a GUI requests an operation. The SLeeLa runtime remains authoritative for permissions, filesystem access, networking, process execution, and administrative operations.
14. JavaFX mapping
JavaFX is an adapter for Guia™, not the protocol itself.
Examples:
CONTROL.CREATE(button)
→ JavaFX Button
EVENT.BIND(button, ACTION)
→ JavaFX event handler
DATA.SUBSCRIBE(model)
→ JavaFX observable/binding layer
CONTROL.UPDATE
→ JavaFX property update
WINDOW.CLOSE
→ JavaFX Stage close
15. Skya integration
Skya's JavaFX client SHOULD use the sequence:
SkyaClient.sleela
↓
CIRCUIT.LOAD
↓
CIRCUIT.START
↓
LISTENER.START
↓
MONITOR.SUBSCRIBE
↓
JavaFX Guia™ adapter
↓
Skya client monitor
The JavaFX monitor is therefore a Guia™ client rather than a second independent control system.
16. Compatibility requirements
A Guia™ implementation MUST:
- identify its protocol version;
- expose its supported capabilities;
- preserve object IDs during an active session;
- reject unknown mandatory operations safely;
- report state transitions;
- preserve message sequence information;
- respect SLeeLa authorization;
- avoid silently changing security policy.
Future revisions MUST document incompatible changes and assign an appropriate protocol version.
17. Reference status
This document is the normative starting reference for Guia™ within SLeeLa.
Guia™ 1.1 — SLeeLa GUI Protocol™
— Max Rupplin - MEARVK LLC - 2026