# `Plushie.RendererEnv`
[🔗](https://github.com/plushie-ui/plushie-elixir/blob/v0.7.2/lib/plushie/renderer_env.ex#L1)

Builds a safe, whitelisted environment for the renderer binary.

The renderer is spawned as a child process via `Port.open/2`. Erlang ports
inherit the parent's full environment by default, which can leak sensitive
variables (API keys, database credentials, tokens) to the renderer.

This module builds an explicit environment from a whitelist. Variables not
on the whitelist are actively unset (set to `false` in Erlang port terms)
so the child process receives only what it needs.

## Usage

    env = Plushie.RendererEnv.build(rust_log: "plushie=error")
    Port.open({:spawn_executable, path}, [{:env, env} | other_opts])

## How it works

Erlang's `{:env, list}` option _extends_ the parent environment rather
than replacing it. To enforce a whitelist, `build/1` emits `{name, false}`
entries for every parent variable that is NOT whitelisted. This causes
Erlang to unset those variables in the child process.

## Whitelist

The whitelist covers:

  * **Display** - `DISPLAY`, `WAYLAND_DISPLAY`, `WAYLAND_SOCKET`,
    `WINIT_UNIX_BACKEND`, `XDG_RUNTIME_DIR`
  * **Rendering** - `WGPU_BACKEND`, `MESA_*`, `LIBGL_*`, `__GLX_*`,
    `VK_*`, `GALLIUM_*`
  * **Library loading** - `PATH`, `LD_LIBRARY_PATH`, `DYLD_LIBRARY_PATH`,
    `DYLD_FALLBACK_LIBRARY_PATH`
  * **Locale** - `LANG`, `LANGUAGE`, `LC_*`
  * **Accessibility** - `DBUS_SESSION_BUS_ADDRESS`, `AT_SPI_*`,
    `GTK_MODULES`, `NO_AT_BRIDGE`
  * **Font** - `FONTCONFIG_*`, `XDG_DATA_DIRS`, `XDG_DATA_HOME`
  * **Renderer** - `RUST_LOG`, `RUST_BACKTRACE`
  * **Home** - `HOME`, `USER`
  * **Plushie toggles** - any variable starting with `PLUSHIE_` (debug
    and diagnostic toggles read by the renderer itself, e.g.
    `PLUSHIE_NO_CATCH_UNWIND`). The prefix is plushie-reserved; no
    legitimate secret should use it.

# `env_entry`

```elixir
@type env_entry() :: {charlist(), charlist()} | {charlist(), false}
```

A single entry for the `:env` option of `Port.open/2`.

# `build`

```elixir
@spec build(keyword()) :: [env_entry()]
```

Builds a whitelisted environment for the renderer Port.

Returns a list of `{charlist_name, charlist_value | false}` tuples suitable
for the `:env` option of `Port.open/2`. Non-whitelisted variables from the
parent environment are explicitly unset (`false`).

## Options

  * `:rust_log` - sets `RUST_LOG`. When provided, overrides any inherited
    value. When `nil`, the parent's `RUST_LOG` is forwarded if present.
  * `:extra` - additional `{charlist_name, charlist_value | false}` pairs
    to merge (e.g. for tests that need to unset specific variables).

# `whitelisted?`

```elixir
@spec whitelisted?(String.t()) :: boolean()
```

Returns `true` if `name` is on the whitelist.

---

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