# SLeeLa `lib/gui` — the SLeeLa-facing GUI vocabulary **Revision:** 0.1 **Family:** `gui` `lib/gui` is the **SLeeLa-facing consequence** of the top-level [`gui/`](../../gui/) work. The `gui/` directory holds the Java host, the native C ABI bridge (`gui/native/sleela_gui_bridge.{h,cpp}`), and the 1..14 document-change listener; `lib/gui` is the `.sleela` contract a SLeeLa program uses to express that same model. The two are kept in correspondence: every class here mirrors a concept documented in [`gui/INTEGRATION.md`](../../gui/INTEGRATION.md) and [`gui/DOCUMENT_LISTENER.md`](../../gui/DOCUMENT_LISTENER.md). ## The division of authority The architecture is intentionally asymmetric (see `gui/INTEGRATION.md`): - **SLeeLa** owns business logic, state transitions, and the *meaning* of events. - **Java** owns Swing/JavaFX presentation and desktop lifecycle. - **The native bridge** is the stable low-level boundary to the C/C++ core. Java is a native desktop *host* for SLeeLa, not a second business-logic implementation. ## Classes | Class | Mirrors (in `gui/`) | Role | |---|---|---| | `SLGuiBackend` | `SleelaGui.create(backend)` | toolkit-neutral backend selector: `swing` / `javafx` (alias `fx`) / `native` | | `SLGuiWindow` | `SleelaGui` | window intent: `show`, `setText`, and the `refresh(id, revision)` document sink | | `SLGuiAction` | `SleelaGuiRuntime.action` / `SleelaGui.onAction` | a named action bound to a SLeeLa operation; take-the-latch activation | | `SLGuiMenuBar` | host menu-bar surface | ordered menu-bar state, visibility, focus, and active-menu navigation | | `SLGuiMenu` | host menu surface | menu visibility/open state, active item navigation, and selection bounds | | `SLGuiMenuItem` | host menu-item surface | enabled/checkable/checked/separator state, icon + shortcut metadata, and one-shot activation latch | | `SLGuiDocument` | `SleelaDocument` | immutable watched-document snapshot: id, path, OS revision (`lastModified:size` / `absent`) | | `SLGuiDocumentListener` | `DocumentListener` | the 1..14 document watch; OS-driven refresh; revision coalescing | | `SLGuiRuntime` | `SleelaGuiRuntime` | **Path 2** — SLeeLa intent drives the window directly | | `SLGuiHost` | `SleelaGuiHost` | **Path 1** — a Java host ties actions/changes to SLeeLa operations | | `SLGuiBridge` | `sleela_gui_bridge.h` | **Path 3** — the shared native ABI (create/call/refresh/destroy) | | `SLGuiIntegration` | `gui/INTEGRATION.md` | the recommended three-path posture | A runnable, self-contained walkthrough is `lib/gui/version-mual/gui-demo.sleela` (the GUI `.sleela` impl now lives in `lib/gui/version-mual/`, with an identical copy in `lib/gui/version-gual/`; `lib/gui/` keeps these docs). ## Menu Contract (MUAL 1.0 Through Military 5.0) All five versioned lines now carry `SLGuiMenuBar`, `SLGuiMenu`, and `SLGuiMenuItem` model classes. These are toolkit-neutral state contracts: SLeeLa owns labels, action names, enabled/checked state, focus/navigation state, and activation latches; the Java/native host owns actual drawing, pointer/keyboard events, accessibility integration, and any native-menu API calls. The widget factories recognize `menubar`/`menu-bar`, `menu`, `menuitem`/`menu-item`, and `menuseparator`/`menu-separator`. The factory currently constructs these using existing box/button/separator primitives, which gives a portable custom-widget fallback. `SLGuiBackend.supportsNativeMenus()` reports whether a backend is eligible to request native menus (`javafx`/`fx` or `native`); this capability flag is not a claim that every host has already wired native menu rendering. The Swing fallback remains custom-rendered. `SLGuiMenuItem.activate()` refuses disabled items, separators, and items without a named action; valid activations toggle checkable state and set a one-shot latch for the host/runtime to consume with `takeActivation()`. The host must dispatch the configured action name/operation, close the menu after ordinary activation, and preserve keyboard focus/navigation semantics. ## Versioned lines: `version-mual` (1.0) and `version-gual` (2.0) The GUI `.sleela` impl is carried in two parallel lines under `lib/gui/`: - **`version-mual` — 1.0 (baseline).** The original 25-class surface. `SLPackage` reports `version() == "1.0"` / `featureLevel() == 1`. - **`version-gual` — 2.0.** The 1.0 surface plus a hardened, settings-first posture. `SLPackage` reports `version() == "2.0"` / `featureLevel() == 2`, and the line adds: - **`SLGuiSettings`** — one validated, nameful settings object gathering the operating knobs: theme (`system`/`light`/`dark`), DPI scale, reduced-motion / accessibility, vsync, window min/max size + resizable/decorations, and the document-listener poll / debounce / coalesce-queue cap / backpressure policy. Every setter **clamps to a safe window**; `honored()` / `report()` state whether the configuration is internally consistent (the clamp-to-window discipline of the `lib/cpu` timing/voltage layer). - **Hardened `SLGuiBackend`** — `configureStrict()` refuses an unknown backend (fail-closed) and capability flags (`supportsHiDpi/Themes/Vsync/Accessibility/NativeMenus`). - **Hardened `SLGuiWindow`** — min/max size, `resizable`/`decorated`, a clamped `resize()`, and `applySettings(SLGuiSettings)`. - **Hardened `SLGuiDocumentListener`** — `configure()` clamps the attached count into the 1..14 contract, plus debounce, a coalesce-queue cap, a backpressure policy (coalesce/drop-oldest/block), and `applySettings(...)`. - **`version-thual` — 3.0.** The 2.0 surface plus a clean, professional **visual-effects** layer. `SLPackage` reports `version() == "3.0"` / `featureLevel() == 3` (`isThreePointZero()`), and the line adds: - **`SLGuiEffects`** — a per-component effect bundle attached to an `SLGuiNode`: lighting + **glow**, **3D shine** highlight, drop **shadow**, a **metal** look-and-feel, **rotation** (fixed or scheduled), **fade** in/out, and an **activation audio** cue. Every knob is clamped; `toStyle()` flattens it into the node's style for the `SLGuiMount` reconciler; `honored()` checks ranges. - **`SLGuiRotationSchedule` (a "schene")** — scheduled rotation on a cadence. Its second role is a **cryptographic rotation cadence for an internal memorandum**: the same tick that turns the visible angle advances a key `epoch()`, so visible rotation is the honest external signal of an internal key rotation. Carries cadence/accounting only (no cipher). - **`SLGuiBranding`** — logo + brand identity (asset, placement, scale, wordmark, accent/secondary colors, tagline) the host paints into the chrome. - **`SLGuiAudioCues`** — the activation-audio registry (named cues → host assets, master enable/mute/gain) a component's effect references by name. - `SLGuiNode` gains `effects()` / `applyEffects()` / `tickEffects()`, and `SLGuiApp` gains `brand()`, `audioCues()`, and an `advanceEffects()` tick in its loop that drives scheduled rotations (and their memo key epochs) + fades. A runnable walkthrough is `version-thual/gui-effects-demo.sleela`. - **`version-dual` — 4.0.** The 3.0 surface plus a rich, professional **component set** and a substantially upgraded aesthetic. `SLPackage` reports `version() == "4.0"` / `featureLevel() == 4` (`isFourPointZero()`), and the line adds: - **`SLGuiAudioRecorder`** — a standard audio-input record control (idle → armed → recording ↔ paused → stopped, level/duration/clip, device + format). - **`SLGuiVideoCanvas`** — a movie surface with full transport (play/pause/ stop/seek, position+duration, volume/mute, loop, rate, fullscreen, buffer). - **`SLGuiUrlBar`** — an HTML-aware, HTTP-driven URL navigation bar (go/back/ forward/reload/stop, bounded history, HTTP status/content-type, HTML-aware). - **`SLGuiClickObject`** — a custom click object: a small circle with architecturally-driven motion (static/drift/orbit/pulse) and a staged "System Apprentice" timer that escalates to a bound **final call**. - **`SLGuiLayout`** — exact positioning (absolute x/y/w/h) + layout modes (flow/grid/anchor/dock) with alignment, padding, gap, anchors. - **`SLGuiGraphics`** — a graphics facility (bounded draw-command list) **and** its control layer (quality, antialiasing, layer, dirty region). - **`SLGuiAdminAuthority`** — admin **sign-in** to start a process, **sign-off** on a component operation, and a **signature for Law**, with a fail-closed, audited authority trail. - **`SLGuiHtmlRenderer`** — a quick-responsive HTML renderer: a parse → style (CSS) → layout → script (JavaScript) → paint pipeline with a configurable time-to-first-paint budget (`quickResponse` / `quickPaintMs`), incremental parsing, and a JS timeout. It is **codec-aware**: `