The behaviour and macro for Dialup page modules.

A page module handles a single route. Place it at the appropriate path under your app_dir and it will be routed automatically:

# lib/app/page.ex         → /
# lib/app/blog/[slug]/page.ex → /blog/:slug

Usage

defmodule MyApp.App.Page do
  use Dialup.Page

  def mount(_params, assigns) do
    {:ok, Map.put(assigns, :count, 0)}
  end

  def handle_event("increment", _, assigns) do
    {:update, Map.update!(assigns, :count, &(&1 + 1))}
  end

  def render(assigns) do
    ~H"""
    <h1>Count: {@count}</h1>
    <button ws-event="increment">+1</button>
    """
  end
end

Callbacks

• mount/2 — called on every page navigation. Receives URL params and the current assigns (which already include session data set by layouts). Return {:ok, new_assigns} or {:redirect, path} / {:redirect, path, assigns} to navigate before render. Defining mount/1 (assigns only) is also accepted as a convenience.
• render/1 — renders the page HTML using HEEx.
• handle_event/3 — called when a ws-event, ws-submit, or ws-change fires.
• handle_info/2 — called for Erlang process messages (e.g. PubSub, timers).
• page_title/1 — optional; return a string to set <title>. Return nil to use the application default.
• agent_state/1 — returns the allowlisted state projection visible to an attached agent.
• agent_message/1 — explains the page concept, operating flow, and safety constraints to an agent that has no source-code context.
• agent_grant/1 — defines capabilities, projections, expiry, and version requirements for HTTP MCP session tokens. The default grant is read-only ([:read_scene]); override explicitly for mutating or built-in tools such as lock_ui.

Human and agent projections

Use <.dialup_action> instead of a plain event button when the same operation should be available to an attached agent. Use <.dialup_region> for stable domain areas that need a semantic name, structured data, or action relationships.

<.dialup_action> is the single boundary for what an agent can do: raw ws-event, ws-submit, ws-change, and ws-href elements are never auto-exposed as tools. To make a navigation link agent-operable, declare it with <.dialup_action navigate="/path">; the same declaration renders the human link and generates the navigation tool.

Action modes

Each <.dialup_action> uses exactly one mode:

See guides/agent-native-app-development.md for Commanded integration and availability derivation.

Return values for handle_event/3 and handle_info/2

Module attributes

• @layout false — disable all layout wrapping (useful for login/fullscreen pages).
• @static true — serve the page without establishing a WebSocket connection.

Colocation CSS

Place a page.css file in the same directory as page.ex. It is automatically scoped to the page at compile time (no build tool required).

Helpers

use Dialup.Page imports overwrite/2, set_default/2, subscribe/2, declare_action/1, declare_region/1, dialup_action/1, and dialup_region/1.