# `OctaStar`

Elixir SDK helpers for Datastar.

The facade functions in this module delegate to small protocol modules while
keeping a pipeline-friendly Plug API:

    conn
    |> OctaStar.start()
    |> OctaStar.patch_signals(%{count: 1})
    |> OctaStar.patch_elements(~s(<div id="count">1</div>))

# `__using__`
*macro* 

Provides Phoenix controller helpers.

Use `use OctaStar, :controller` in your `AppWeb.controller/0` macro
instead of `use OctaStar.Phoenix.Controller` directly:

    def controller do
      quote do
        use Phoenix.Controller, formats: [:html]
        use OctaStar, :controller
      end
    end

# `check_connection`

```elixir
@spec check_connection(Plug.Conn.t()) ::
  {:ok, Plug.Conn.t()} | {:error, Plug.Conn.t()}
```

Checks whether a chunked SSE connection still accepts writes.

# `console_log`

```elixir
@spec console_log(Plug.Conn.t(), term(), keyword()) :: Plug.Conn.t()
```

Logs a value to the browser console.

# `execute_script`

```elixir
@spec execute_script(Plug.Conn.t(), String.t(), keyword()) :: Plug.Conn.t()
```

Executes JavaScript in the browser by appending a script element.

# `patch_elements`

```elixir
@spec patch_elements(Plug.Conn.t(), iodata() | tuple() | nil, keyword()) ::
  Plug.Conn.t()
```

Patches one or more complete HTML elements into the DOM.

# `patch_signals`

```elixir
@spec patch_signals(Plug.Conn.t(), map(), keyword()) :: Plug.Conn.t()
```

Patches client-side Datastar signals using RFC 7386 JSON Merge Patch semantics.

# `patch_signals_raw`

```elixir
@spec patch_signals_raw(Plug.Conn.t(), String.t(), keyword()) :: Plug.Conn.t()
```

Patches client-side Datastar signals from a pre-encoded JSON string.

# `read_signals`

```elixir
@spec read_signals(Plug.Conn.t()) :: map()
```

Reads Datastar signals from a Plug connection.

Returns a signal map. Raises `OctaStar.Signals.ReadError` when the
payload cannot be decoded. Plugs that need `{:ok, map()} | {:error, term()}`
should call `OctaStar.Signals.read/1` instead.

# `read_signals!`

```elixir
@spec read_signals!(Plug.Conn.t()) :: map()
```

Reads Datastar signals from a Plug connection, raising on invalid JSON.

# `redirect`

```elixir
@spec redirect(Plug.Conn.t(), String.t(), keyword()) :: Plug.Conn.t()
```

Redirects the browser by executing a tiny client-side script.

# `remove_elements`

```elixir
@spec remove_elements(Plug.Conn.t(), String.t(), keyword()) :: Plug.Conn.t()
```

Removes elements from the DOM by CSS selector.

# `remove_signals`

```elixir
@spec remove_signals(Plug.Conn.t(), String.t() | [String.t()], keyword()) ::
  Plug.Conn.t()
```

Removes signals by setting one or more dot-notated signal paths to `null`.

# `send`

```elixir
@spec send(Plug.Conn.t(), String.t(), [String.t()] | String.t(), keyword()) ::
  Plug.Conn.t()
```

Sends a raw Datastar SSE event and returns the updated connection.

# `start`

```elixir
@spec start(Plug.Conn.t()) :: Plug.Conn.t()
```

Starts a Server-Sent Events response on a Plug connection.

# `start_stream`

```elixir
@spec start_stream(Plug.Conn.t(), term()) :: Plug.Conn.t()
```

Starts an SSE stream with per-tab deduplication.

Requires `OctaStar.Utility.StreamRegistry` in your supervision tree
and a `tabId` signal in your root layout. See
`OctaStar.Utility.StreamRegistry` for setup.

---

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