Runtime contract — SSR, hydration, islands, and the data-fui-* reference

<!--
SYNC NOTE: this doc is an embedded extract of core-ui/ARCHITECTURE.md,
which is the repo's source of truth for the UI/runtime contract. The
two must be kept in sync: when the model or the attribute table
changes there, update this file in the same commit.
framework/docs/docsynctest.go fails when an attribute documented in
core-ui/ARCHITECTURE.md is missing here.
-->

This page carries the runtime contract for readers of the embedded
docs (gofastr docs, the framework_docs_* MCP tools): the
SSR/hydration/island/SSE model and the full data-fui-* attribute
reference. If you are working inside the framework repo, read
core-ui/ARCHITECTURE.md instead — it is the authoritative version
and adds the recipes, the styling contract, and the component
cheat sheet.

The model in one paragraph

Every page is server-rendered (SSR) on first request — full HTML, full
data, no skeleton, no client-side data fetch on initial load. The browser
receives the rendered page and runtime.js hydrates the existing DOM:
attaches event listeners, signal bindings, SSE streams. After hydration,
page-to-page navigation is client-side (Angular-router style: pushState,
partial fetch, swap content, with cache so back is instant — no hard
refreshes). Interactions that change state inside the current page are
handled by islands: a click triggers an RPC to the server-side island
handler, which returns the updated island HTML; the runtime swaps just
that island's content. The rest of the page stays put. Passive freshness
is polled: a region with data-fui-poll (or a widget with
Builder.Poll) re-fetches server-rendered HTML on an interval — no held
connection, no cross-replica infrastructure. Server-pushed updates
(e.g. another user changed something) flow through signals + SSE to update
bound DOM nodes without any client action — reserved for semantics that
need the connection itself (presence, collaboration, sub-second updates).
The full escalation ladder — client signals → RPC → poll → SSE push — is
reactivity; the interactive layer is stateless (sessions
are signed tokens, state lives in the DB or the client signal store), so
any replica serves any request.

The five scenarios

Forms and mutations follow the in-page pattern: POST to the island's
RPC handler, response carries the new island HTML.

What is an island?

An island is a server-rendered, server-driven component with its own
RPC endpoints and (optionally) signal bindings. It owns:

1. Its rendered HTML (SSR).
2. Its server-side state (in memory or DB).
3. Its update logic (handlers that re-render and respond).

Pagination is an island. A sortable table is an island. A "favorite" toggle
on a card is an island. A page header that needs to react to user-scope
changes is an island. Inline content that never changes (a static
heading, a piece of marketing copy, a footer) is not an island — it's
just rendered HTML.

Islands are built with the core-ui/widget builder (see
widgets) or wired by hand with the attributes below (see
interactive-patterns → "Writing a
hand-written island, end to end").

Runtime primitives (the wiring)

The runtime understands a small set of data-fui-* attributes on the
hydrated DOM. You don't write JavaScript — you compose these on the
server side and the runtime does the work.

For the authoritative list, grep data-fui- in
core-ui/runtime/runtime.js. Adding a new attribute requires updating
core-ui/ARCHITECTURE.md, this extract, and a runtime test.

Component-action attributes (the compiled data-action family, distinct
from the data-fui-* runtime primitives above): data-action="<name>" on an
element inside a [data-component] binds the named compiled action to that
element's click (and data-action-<event> / data-action-type to
input/change/submit). data-action-mount="<name>" fires the named action
once on hydration (and again after each SPA nav) — the hook a server-rendered
island uses to populate itself on load, since the other triggers are
user-event-driven. Any data-param-* on the element flows into the handler's
params. Covered by core-ui/runtime/action_mount_e2e_test.go.

Response headers the runtime understands:

Screen cache + invalidation. The router keeps a 20-entry LRU of
rendered screens keyed by pathname+search (the initial page included)
so back/forward is instant. Eviction never re-renders the visible page —
an RPC that changed what the current screen shows should return island
HTML or use data-fui-rpc-navigate; the header exists for screens you
are not on (an admin action that stales /pricing, a create that
stales every page of a list). The JS mirrors are
__gofastr.invalidate(...selectors) (same selector rules as the header)
and __gofastr.refresh() (re-fetch and re-render the current screen,
bypassing the cache). Scope is per tab: the header only reaches the tab
whose request carried it, and an evicted entry costs nothing until that
tab actually navigates — surfaces that must stay fresh across tabs
belong on the polling rung (data-fui-poll), not on cache eviction.
Iframe embeds have no screen cache, so the header is a no-op there.

The flow for an in-page update (e.g. clicking "page 2" on a pagination island):

[click]  → button has data-fui-rpc="/island/customers/page" data-fui-rpc-method="POST" data-fui-rpc-signal="customers-rows"  → runtime POSTs {"page": 2}  → server handler computes new rows, renders HTML, returns it  → runtime treats the response body as the new value of signal "customers-rows"  → every node with data-fui-signal="customers-rows" data-fui-signal-mode="html" gets innerHTML replaced  → no URL change, no <main> swap, no other DOM touched

Forms

Default: forms behave like standard HTML forms. The runtime only
intercepts a form when you explicitly ask it to, so auth flows,
file uploads, password-manager UX, and Location-follow redirects
work the moment you drop a <form> into the page.

When the runtime intercepts

Every other form — no special attribute, default or urlencoded or
multipart/form-data enctype — is NOT intercepted. The browser
submits it the standard way: POST body matches enctype, Set-Cookie
headers apply, 303→Location is followed, file inputs upload natively.

Server redirects (after intercept)

When the interceptor IS active and the handler responds with a 30x

• Location header, the runtime navigates to the location via the

SPA navigator (no hard refresh between same-app pages), falling back
to window.location.assign. For the non-intercepted default path,
redirect-following is the browser's own job — same result.

<!-- gofastr:compile
import "net/http"
var w http.ResponseWriter
var r *http.Request
-->

http.Redirect(w, r, "/dashboard", http.StatusSeeOther)

Cookie-set + redirect: the canonical auth flow

// /auth/login form handler — battery/auth ships this out of the box.http.SetCookie(w, sessionCookie)http.Redirect(w, r, successRedirect(r, "/"), http.StatusSeeOther)

The runtime preserves the cookie and follows the redirect, so a form
POST to /auth/login from an SSR login page lands the user on the
next screen without a hard refresh — and without the host needing
client-side glue.

Heavy-JS plugin markers

Pages that mount a sandboxed heavy-JS plugin (see
plugin-platform) carry a mount marker emitted by
framework/pluginhost.MountMarker: data-fui-plugin="<name>" with
data-fui-plugin-docid, data-fui-plugin-doc (server-rendered initial
JSON), data-fui-plugin-minheight, and data-fui-plugin-capabilities
(the grant set, resource:verb grammar). These are scanned by the plugin
host broker — a separate script served at its own route, NOT part of
runtime.js or its budgets. Plugins may add namespaced extras (the
wysiwyg editor adds data-fui-plugin-for naming its hidden form fields);
those are documented by the owning plugin.

See also

• UI capability map maps product architectures to this runtime boundary and its scaling semantics.
• UI composition recipes turns that architecture into product-shaped page grammar.
• Events and SSE defines best-effort push and durable alternatives.

Common mistakes

These are the misreadings of the model that have already cost rework
(they are cataloged as "failure modes" in core-ui/ARCHITECTURE.md):

• Intercepting all link clicks for SPA. State-change interactions
  like pagination should not be <a href="?p=2"> links at all — they
  are island RPCs. Cross-page navigation (/a → /b) IS intercepted
  by design; don't disable that to "fix" an in-page interaction that
  should never have been a route.
• Making every interaction a full navigation. Clicking a sort
  header must not reload the page — that's a hard refresh, which the
  model rules out for in-page state. Use an island RPC.
• Making every interaction client-only after hydration. Client-
  managed pagination state only works for datasets that fit in one
  render, and it duplicates server logic. Islands are server-driven;
  let the server do the math and return HTML.
• Shipping CSS from the app or a generator to make a surface look
  right. All styling lives in the design system (component CSS via
  registry.RegisterStyle, layouts via core-ui/app, tokens via
  core-ui/style). A surface that needs CSS the components don't
  provide is a design-system gap to fix upstream — see
  theming.
• Delivering a user action's response over SSE. SSE is push-only
  (background events). The result of a user action arrives in the RPC
  response itself. See Optimistic UI for the full
  mutation lifecycle.