Home /Modules/docs/SLEELA_GUI_PROTOCOL.md

SLEELA_GUI_PROTOCOL.md

docs/SLEELA_GUI_PROTOCOL.md · 707 line(s) · markdown

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:

Names are case-sensitive. Implementations MUST NOT reuse an active object ID.

3. Core objects

3.1 GuiApplication

Represents the GUI process/application.

Fields:

3.2 GuiClient

Represents the SLeeLa-facing GUI client.

Fields:

3.3 GuiListener

Represents the event/message listener receiving SLeeLa events.

Fields:

3.4 Circuit

Represents a loaded SLeeLa circuit.

Fields:

3.5 Session

Represents one GUI-to-client interaction session.

Fields:

3.6 Control

Base GUI control.

Fields:

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:

3.8 Command

Represents an operation callable by the GUI.

Fields:

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:

  1. GUI.CREATE
  2. CLIENT.CREATE
  3. LISTENER.CREATE
  4. SESSION.CREATE
  5. CLIENT.CONNECT
  6. LISTENER.START
  7. SESSION.OPEN
  8. SESSION.AUTHENTICATE when required
  9. CIRCUIT.LOAD
  10. CIRCUIT.START
  11. LISTENER.SUBSCRIBE
  12. GUI.SHOW
  13. APP.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:

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