otoe 0.1.8

Experimental Python UI runtime with reactive components and live previews.

Otoe

Otoe is an experimental Python UI runtime for operational interfaces: write reactive components, preview them as HTML, test them headlessly, render deterministic native frames, and build offline bundles for constrained Linux targets.

The project is still pre-alpha. The core runtime, HTML preview path, headless native spike, and offline bundle pipeline are active technical-preview surfaces; Otoe is not yet a stable public framework or production desktop renderer. Readable native PNG text is available through the optional Pillow-backed renderer path; the default native renderer stays dependency-free and deterministic.

What Works Today

• Python component functions with explicit widget props and event contracts.
• signal, computed, effect, lifecycle cleanup, Show, and keyed For.
• Static HTML rendering and live HTML preview support for live-preview apps.
• A small portable style layer through css(...), StyleSheet, and utilities.
• otoe.ui primitives for app frames, cards, badges, action buttons, tabs, tables, dialogs, toasts, command palettes, sidebars, menus, selects, lists, and metric surfaces.
• Headless native layout, paint, PNG output, hit testing, click, focus, keyboard, input, and scroll dispatch through NativeSurface.
• Offline planning, dependency audit, build, generated runner validation, and pack commands for the first hardware/cage profile.
• Backend-candidate evidence tooling around RenderTree, styleOps, coverage declarations, and an experimental external Path0 JSON runner.

Not Ready Yet

• Stable API guarantees.
• Production native rendering, GPU rendering, real text shaping, or retained desktop windowing.
• Platform accessibility tree output.
• Full browser CSS compatibility.
• A complete native-parity component library.

Quick Start

Use Python 3.11 or newer.

python -m pip install otoe
otoe new hello_otoe
cd hello_otoe
otoe dev app:app --css styles.css
otoe render app:app --out preview.html --css styles.css --pretty
otoe render app:app --out preview.png --native --css styles.css
otoe render app:app --out [e-mail] --native --native-scale 2 --css styles.css
otoe build app:app --out dist/cage --css styles.css --validate

otoe new writes a small renderable app plus styles.css. otoe dev serves the scaffold as a local live HTML preview; the HTML render is the fastest static visual check; the native PNG render exercises the current headless native spike; --native-scale writes higher-density deterministic PNGs without changing layout units; the build command writes and validates a minimal offline bundle. For readable native PNG text during local previews, install otoe[native-text] and render with --native-text pillow; deterministic offline bundles declare their font through [native.text] in otoe.profile.toml.

For local development from a checkout:

python -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
pytest -q

Repository examples such as examples.quickstart:app are available from a source checkout, not from the installed wheel:

PYTHONPATH=src:. python -m otoe render examples.quickstart:app --out preview.html --pretty
PYTHONPATH=src:. python -m otoe render examples.quickstart:app --out preview.png --native
PYTHONPATH=src:. python -m otoe dev examples.live_counter:app --port 8767

Tiny Example

from otoe import Button, Text, VStack, component, computed, mount, signal


@component
def Counter():
    count = signal(0)
    label = computed(lambda: f"Clicked {count.value} times")

    return VStack(
        Text(label),
        Button("Increment", onClick=lambda: count.set(count.value + 1)),
        gap=8,
    )


tree = mount(Counter())

Product Shape

Otoe should not be read as a generic replacement for Qt, Flutter, or browser apps. The strongest current niche is Python-first operational software:

• hardware control panels
• kiosks and appliance UIs
• internal dashboards
• offline-testable local tools
• renderer/backend experiments that need deterministic evidence

The backend and evidence tooling is intentionally advanced and experimental. New app authors should start with otoe new, HTML/native render, and the portable UI subset before reaching for backend-candidate commands. Use otoe portable-core to inspect the current Portable Core UI v0 support matrix from the installed package. The Phase 5 professional reference apps are documented in REFERENCE_APP_PATTERNS.md and validated through the hardware, admin, data workflow, utility, SaaS, and UI examples.

Documentation

• Quick Start
• Concepts
• API Tiers
• Portable Core UI v0
• Hardware Control Panel Demo
• Native Layout
• Native Status
• Offline Build
• Backend Candidates
• Release Checks
• Examples Guide
• Reference App Patterns
• Style Guide
• Testing Guide
• Native Workflows
• Backend Candidate Guide
• Roadmap

Repository Map

• src/otoe/ - runtime package.
• tests/ - runtime, renderer, build, and example regression tests.
• examples/ - source-checkout validation surfaces and case studies.
• preview/ - generated preview artifacts.
• docs/ - product-facing guides and support matrices.
• ADR-*.md - design decisions. ADR-019-native-pillow-text-backend.md records the first real native text backend choice, and ADR-020-native-layout-v0-v1-decision.md records the stack-first native layout v0/v1 boundary.

Status

Current status: post-v0.1.8 workshop hardening. The test baseline is 758 passing tests with optional typing/Pillow tests skipped when those dependencies are unavailable. See ROADMAP.md for the active phase plan.

License

MIT License. Copyright (c) 2026 Forvara.