page

The page surface turns a machine into a web application. Instead of returning JSON to an API client, the machine serves a web page that end users interact with in a browser. This is Kanvas, the interface layer where machines become visible to the people who use them.

Overview

When a browser visits the page URL, Kanvas renders the machine’s output as an interactive web page. You do not write HTML, CSS, or React. Kanvas generates the interface from the machine’s typed output: lists render as tables or card grids, text as formatted content, numbers as metrics, and maps as structured data views. The output types from responds with determine the rendering.

Page surfaces use session-based authentication, unlike API surfaces which use token-based authentication.

Syntax

expresses
  page
    path: "/"
    title: "Order Dashboard"

A complete machine with a page surface:

machine order_dashboard

  accepts
    customer_id as text

  responds with
    orders as list
    total_value as number

  ensures
    permissions
      allowed to
        reason, http

  implements
    ask fetch_orders, from: "@mashin/actions/http/get"
      url: "https://api.internal.com/orders?customer=${input.customer_id}"
      returns
        body as map
      assuming
        body: {orders: [{id: "ord_1", amount: 50}], total: 50}

    compute format
      {orders: steps.fetch_orders.body.orders, total_value: steps.fetch_orders.body.total}

  expresses
    page
      path: "/"
      title: "Order Dashboard"

Configuration options

Config	Required	Default	Description
path	Yes	-	URL path for the page
title	No	Machine name	Page title shown in the browser tab

Output rendering

Kanvas renders machine output based on the types declared in responds with:

Output type	Rendering
Lists	Tables or card grids
Text	Formatted content
Numbers	Metrics or charts
Maps	Structured data views
Nested structures	Expandable sections

How pages differ from API surfaces

Concern	API surface	Page surface
Client	HTTP client (code)	Browser (human)
Response	JSON	HTML page
Interaction	Single request/response	Navigable interface
Authentication	Token/API key	Session-based

Governance

Every page view is governed:

1. The user is authenticated (session-based)
2. The machine’s ensures permissions are checked
3. The machine executes
4. A SurfaceAccess event is recorded with :page surface in the behavioral ledger
5. Kanvas renders the result

Navigation within the page (clicking a link, expanding a section) may trigger additional machine executions, each individually governed and recorded. For public pages that do not require sign-in, the user’s identity is recorded as “anonymous” in the ledger.

Example

Multiple pages on one machine:

expresses
  page
    path: "/"
    title: "Dashboard"
  page
    path: "/settings"
    title: "Settings"

Combining a page with WebSocket for live updates:

expresses
  page
    path: "/dashboard"
    title: "System Metrics"
  websocket
    path: "/ws/metrics"

Kanvas wires these together automatically: when a page and a WebSocket share the same machine, the page subscribes to the WebSocket for real-time updates.

Pages are accessible locally at http://localhost:9000/, on cloud cells at https://myorg.mashin.live/, or through the tunnel with mashin tunnel.

See also

• expresses - Parent section for all surfaces
• websocket - WebSocket surface (pairs well with pages)
• api - REST API surface (programmatic alternative)