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}. 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.

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.

Ordinary visible DOM elements remain available for human spatial references, but their generated selectors are less stable than region IDs. See guides/agent-native-app-development.md for the complete implementation workflow.

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.