Page runtime and state API

This guide describes Page lifecycle and the IPageState integration API. For the visual authoring procedure, use Create Pages; for shared ownership and route concepts, use the interface guide.

Pages are created from a Flow and retain that Flow’s boardId. Open them from Explorer → UI in their owning Flow.

Page, Event, and Route

These are separate records:

Record	Owns
Page	Components, widget references, canvas settings, layout, lifecycle hooks, and metadata
Event	The board and node to run, execution mode, event interface, and optional `default_page_id`
Route	Only a URL `path` and the `eventId` that handles it

A navigable Page is resolved in two steps:

The route maps a pathname to an app event.
The event’s default_page_id selects the Page.

The Page does not need a separate route object pointing directly to it. See Routes for the current mapping API.

Flow snapshots include the Pages listed by that Flow. For a pinned Event, runtime Page resolution loads the Page from the Event’s board_version. An unpinned Event loads the latest Page. The Page Builder loads the latest Page independently of Studio’s selected graph version; see snapshot boundaries.

Create a Page

Follow Create Pages to add a Page from its Flow. Studio opens it in an editor tab. The standalone Page Builder URL remains available for links and integrations; it is described below.

Page Builder

The Page Builder hosts the shared WidgetBuilder component and adds Page-specific behavior around it:

a Page switcher when the app has multiple Pages;
an Open Flow button when the Page has a board;
automatic saving and a visible saving/unsaved/saved state;
Page settings for behavior, layout, and SEO;
the global FlowPilot assistant with the active surface as context.

The builder URL accepts:

/page-builder?id=<pageId>&app=<appId>&board=<boardId>

board is optional in the URL, but a Page created from a Flow stores its board association and uses it to discover available Simple Event nodes.

Current Page Model

The public state interface stores the following core fields:

interface IPage {
  id: string;
  name: string;
  route?: string;
  content: PageContent[];
  layoutType: "Freeform" | "Stack" | "Grid" | "Sidebar" | "HolyGrail";
  components: SurfaceComponent[];

  boardId?: string;
  canvasSettings?: {
    backgroundColor?: string;
    backgroundImage?: string;
    padding?: string;
    customCss?: string;
  };

  onLoadEventId?: string;
  onUnloadEventId?: string;
  onIntervalEventId?: string;
  onIntervalSeconds?: number;
  noCache?: boolean;

  title?: string;
  meta?: PageMeta;
  widgetRefs?: Record<string, IWidgetRef>;
  version?: [number, number, number];
  createdAt: string;
  updatedAt: string;
}

components is the editable A2UI surface. widgetRefs stores the Widget definitions needed by Widget instances on that Page.

Page Settings

General

Edit the Page name and description, inspect the immutable Page ID and current version, and save metadata explicitly.

Behavior

A Page can invoke Simple Event nodes from its connected Flow:

Hook	When it runs
On Page Load	After the Page is loaded
On Page Unload	When the user navigates away
On Interval	Repeatedly at a positive interval in seconds

A Page with an On Load event renders its layout immediately, together with the last output its load event rendered for the same user, route and query. The load event then refreshes that output in place, and a thin progress bar shows until it renders. Turn on No cache to show only fresh output: the Page then displays a loading screen until the load event renders.

The settings panel only lists events_simple nodes from the connected board. If the list is empty, add a Simple Event node to that Flow.

Layout

The current layout choices are:

Type	Intended use
`Freeform`	Position elements freely
`Stack`	Build a vertical composition
`Grid`	Arrange content on a grid
`Sidebar`	Combine main content and a sidebar
`HolyGrail`	Use the classic header, columns, and footer pattern

Canvas settings control the background color or image, outer padding, and custom CSS. Component-level responsive styling remains part of the A2UI component graph.

SEO

Set the Page title, meta description, favicon, and theme color. These values describe the Page; they do not configure its app route.

State API

interface IPageState {
  getPages(appId: string, boardId?: string): Promise<PageListItem[]>;
  getPage(appId: string, pageId: string, boardId?: string): Promise<IPage>;
  createPage(
    appId: string,
    pageId: string,
    name: string,
    route: string,
    boardId: string,
    title?: string,
  ): Promise<IPage>;
  updatePage(appId: string, page: IPage): Promise<void>;
  deletePage(appId: string, pageId: string, boardId: string): Promise<void>;
}

Although createPage takes a route argument, exposing a Page to users requires an Event and a path → eventId route mapping.

Saving and Previewing

Component and Widget-reference changes are saved after a short debounce. Page metadata and canvas settings use their own shorter debounce, and the settings panel also offers an explicit metadata save.

Use Preview to test the surface at Desktop, Laptop, Tablet, Mobile, or Mobile Small dimensions. Test lifecycle events against representative data before publishing the app.

Continue

Visual Builder: learn every part of the shared editor
Widgets: create reusable blocks for Pages
Routes: expose a Page through an Event