# `Harlock`
[🔗](https://github.com/thatsme/harlock/blob/v0.2.0/lib/harlock.ex#L1)

Harlock — a pure-Elixir TUI framework for Unix terminals.

The two entry points:

  * `Harlock.run/2` — blocking. Starts the app, returns when it exits.
  * `Harlock.start_link/2` — non-blocking. Returns a supervisor pid for
    embedding inside an existing OTP application.

v0.1 is under construction; the smoke functions are scaffold tooling.

# `app`

```elixir
@type app() :: module()
```

# `init_arg`

```elixir
@type init_arg() :: any()
```

# `run`

```elixir
@spec run(app(), init_arg(), keyword()) :: {:ok, term()} | {:error, term()}
```

Start an app and block until it exits. Returns `{:ok, reason}` on normal
exit, `{:error, reason}` if the supervisor failed to start.

The caller's process is linked to the app supervisor, so killing the caller
tears down the supervisor cleanly — which in turn restores the terminal.

Options:

  * `:theme` — a `Harlock.Theme.t()` (or keyword list / map convertible
    via `Harlock.Theme.build/1`). Defaults to `Harlock.Theme.default/0`.

# `smoke`

```elixir
@spec smoke() :: binary() | {:error, term()}
```

Round-trip smoke test. Opens /dev/tty, writes a greeting in the alt-screen,
reads up to 5 bytes from the user, echoes what was typed, and restores the
terminal. Should leave the terminal in a usable state after returning.

# `smoke_crash`

```elixir
@spec smoke_crash() :: {:ok | :no_cleanup | term(), term()}
```

Crash-path smoke test. Spawns a linked child that opens /dev/tty and then
raises. `with_raw`'s nested `try/after` blocks restore the terminal before
the process dies. Returns `{cleanup, reason}` where cleanup is `:ok` if
the restore ran.

# `start_link`

```elixir
@spec start_link(app(), init_arg(), keyword()) :: Supervisor.on_start()
```

Start an app under the caller's supervision tree without blocking.

Returns `{:ok, sup_pid}`. The caller is responsible for handling the
supervisor's lifecycle (linking, monitoring, stopping). Useful when
embedding Harlock inside a larger OTP app — e.g. a Phoenix project with a
dev-mode TUI dashboard.

Accepts the same options as `run/3`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*