# Kael

> Kael is a GPU accelerated Rust application framework for native desktop and
> WebAssembly/WebGL2. Kael 0.4 is a pre 1.0 production candidate using Rust
> 1.97.1 and Rust 2024.

## Start here

- Guide: https://augani.github.io/kael/
- Why Kael: https://augani.github.io/kael/why-kael.html
- Framework today: https://augani.github.io/kael/framework-today.html
- Object guide: https://augani.github.io/kael/object-guide.html
- One codebase: https://augani.github.io/kael/one-codebase.html
- Remaining work: https://augani.github.io/kael/remaining-work.html
- Core API: https://docs.rs/kael
- Component API: https://docs.rs/kael_ui
- Repository: https://github.com/Augani/kael

## Architecture

- `kael` owns the application runtime, entities, elements, retained rendering,
  layout, text, input, accessibility, windows, and platform backends.
- `kael_ui` is the optional component system. `kael` never depends on it.
- Focused `kael_*` crates cover storage, networking, documents, diagnostics,
  media, sharing, notifications, release, and engine services.
- WebView is an optional compatibility island. It is not the default UI model.

## Working model

- Start the runtime with `Application::try_new()?.run(...)`.
- Implement `Render` for views.
- Put retained state in `Entity<T>` values created with `cx.new`.
- Update with `entity.update(cx, |state, cx| { ... })` and call `cx.notify()`
  when the view must render again.
- Use `div()` and `Styled` for primitive layout.
- Call `kael_ui::init(cx)` once when using `kael_ui`.
- Read component tokens with `Theme::of(cx)`.

## Browser target

The browser uses the same Rust state, view, layout, input, virtualization, and
animation code. It renders the retained scene with WebGL2. Pointer, wheel,
keyboard, IME, clipboard, drag and drop, accessibility, and animation frames are
interactive.

Normal Kael applications do not need product JavaScript. `kael web build`
generates `app.js` as Wasm bootstrap glue. Custom JavaScript is needed only for
unwrapped Web APIs, service workers, vendor SDKs, DOM widgets, or host page
integration.

Build references:

- Browser runtime: https://augani.github.io/kael/browser.html
- Deployment: https://augani.github.io/kael/web-deployment.html
- Install `wasm32-unknown-unknown`, `wasm-bindgen-cli` 0.2.122, and Binaryen 132.
- Run `kael web serve --debug` for development.
- Run `kael web build` for optimized `dist/web` output.
- Use `--html <file>` and `--assets <directory>` for a product web shell and assets.
- Deploy `index.html`, `app.js`, and `app_bg.wasm` together.
- Serve Wasm as `application/wasm`.

## Platform accuracy

Query `CapabilityReport::current()` before using an operating system service.
`Full` is ready. `Partial` and `RequiresInit` need a fallback or setup path.
`Unsupported` has no backend. `Disabled` needs a compile time feature.

Do not claim that Kael 0.4 provides native push registration, spellcheck,
geolocation, USB, HID, serial, Bluetooth, outbound promised file drag, share
receivers, or a complete server sent events transport. Browser native paths,
subprocesses, keychain access, global hotkeys, and detached OS windows are also
unavailable.

Kael document crates work with Office and PDF bytes. They are not complete
Office layout, spreadsheet calculation, slide playback, or PDF authoring
engines. `PortableScene2d` is a 2D foundation, not a complete 3D game engine.

## Source map

- Exports: `crates/kael/src/kael.rs`
- Application and entities: `crates/kael/src/app.rs`
- Elements: `crates/kael/src/elements/`
- Platform backends: `crates/kael/src/platform/`
- Capability table: `crates/kael/src/platform_caps.rs`
- Browser CLI: `crates/kael-cli/src/web.rs`
- UI exports: `crates/kael_ui/src/lib.rs` and `prelude.rs`
- Components: `crates/kael_ui/src/components/`, `display/`, `navigation/`,
  `overlays/`, and `charts/`
- Showcase: `crates/kael_ui/examples/astryx_showcase.rs`

Prefer the smallest public API that performs the task. Preserve fallible
boundaries and platform errors. Use WebView only for an intentionally web owned
surface.