Runtime contract: SSR, hydration, islands, and the data-cui-* reference

This page carries the runtime contract for readers of the embedded docs (gofastr docs, the framework_docs_* MCP tools from framework/docs/mcptools): the SSR/hydration/island/SSE model and the full data-cui-* 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-cui-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-cui-* attributes on the hydrated DOM. You don't write JavaScript; you compose these on the server side and the runtime does the work.

Who owns which prefix

Every class and data-* attribute the framework emits carries the prefix of the tree that DEFINES it, and a lower layer never names an upper layer's vocabulary. The gate is core-ui/check.LintLayerPrefixJS / LintLayerPrefixGo, run over the kernel and headless trees by their own test suites.

What this rules out, each a shape that shipped before v0.87.0: a kernel module that names a kit class (fui-notification__title, fui-field__error, fui-copied), a headless module that mounts a kit container (fui-toast-stack-auto), and a kit class an app's owned sheet overrides. The fix shapes are a hook the lower layer declares (data-hui-field-error, data-hui-copy-state), a template the kit registers for the lower layer to clone (registry.RegisterTemplate, preset.ToastTemplate), or a module the kit ships itself (framework/ui/searchinput.js, filedropzone.js, lightbox.js).

The data-fui-* keys that remain are the framework's own modules' and hosts': data-fui-lightbox* and data-fui-zoomed (the kit's lightbox module), data-fui-dropzone-preview* (its dropzone module), data-fui-pane* (its pane host), data-fui-z-tier (ui.Sticky's sheet), data-fui-network-retry-*, data-fui-plugin* (framework/pluginhost) and data-fui-page-loading (framework/uihost). Every other attribute the runtime reads is data-cui-*, in the table below.

RPC writes send Content-Type: application/json even when an action has no body (for example a state move or restore). Bodyless GET and HEAD requests carry no content type. Multipart RPC forms let the browser set multipart/form-data with its boundary.

For the authoritative list, grep data-cui- 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-cui-* 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. Markup inserted outside a navigation (an intercepted route's overlay, an island swap, a widget's chrome) fires its mounts too, each element once, through the actionloader module a page with compiled actions loads (boot marks what its own pass fired). The module also fetches the compiled action script of a component such markup brings (retrying one that failed to load), then fires that component's mounts once it registers (core-ui/runtime/action_mount_inserted_e2e_test.go, actionloader_inserted_e2e_test.go).

Response headers the runtime understands:

Layer-key encoding. X-Gofastr-Swap percent-encodes C0 control bytes, DEL, non-ASCII bytes and literal percent signs. Decode it once with decodeURIComponent to recover the DOM's layout key.

Deploy skew: X-Gofastr-Markup. Every navigation request the runtime makes (the click's partial fetch, the envelope navigator, prefetch, intercepted overlays) names the markup generation its kernel reads in X-Gofastr-Markup (window.__gofastr._markup, runtime.MarkupVersion in Go: 2 is the data-cui-* spelling, 1 the data-fui-* one through v0.86). A tab opened before a deploy keeps its runtime, and markup that kernel cannot read leaves every interactive marker dead: a data-cui-rpc form submits as a native GET with its fields in the URL. When a browser script fetch (Sec-Fetch-Mode of cors, same-origin or no-cors) names another generation or none, uihost answers 409 with an HTML partial at the swap key the live DOM holds, carrying a <meta http-equiv="refresh"> to the destination and a reload link. Every runtime applies an HTML partial the same way, so inserting it starts the browser's own navigation and the destination loads whole with the current runtime. A request without Fetch Metadata (curl, a Go test, a browser older than Safari 16.4) gets the ordinary partial. An old runtime's cross-chain navigation fetches the whole document with no navigate header, which the server cannot tell from app code fetching a page, so it is not covered. Bump the generation in frag/kernel.js and core-ui/runtime/markup.go together when the attribute vocabulary changes again.

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-cui-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). A forced fetch (refresh(), navigate(path, {force: true}), data-cui-rpc-navigate) joins a navigation already fetching the same path, never one replaying a cached or prefetched copy: that copy is what the force exists to replace. 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-cui-poll), not on cache eviction. Iframe embeds have no screen cache, so the header is a no-op there.

Keyboard containment. Widgets, intercepted drawers, trap disclosures and responsive pane overlays use tabbable controls for their initial-focus handoff and Tab-cycle boundaries. A negative tabindex excludes every element type, including native links and form controls; normalization uses the browser's numeric tabIndex, so values such as -7 and -12 are excluded too. Explicit autofocus and programmatic focus targets remain separate from the sequential Tab order.

Same-destination navigation. __gofastr.navigate(path) compares the resolved same-origin URL, including its query and fragment, with the current URL before writing history. An identical destination is a no-op, including an equivalent absolute URL. Changing or removing a fragment is a distinct navigation. {force: true} still fetches again and replaces the current entry when the complete destination is unchanged.

Combobox link options commit their input value and close their list even when the link router has already claimed the click. They do not start a second navigation or bypass a cancelled gofastr:beforenavigate event. Keyboard picks, and clicks the router has not claimed, navigate once through the picker instead.

Cancelling a navigation (gofastr:beforenavigate). The router dispatches this cancelable event on the anchor element (bubbles, cancelable, so a document-level listener sees it and target is the link) immediately before committing an intercepted click — after every fall-through check, so it fires only for clicks the router would actually handle. detail carries href (the raw attribute value), path (the resolved path+search the router would navigate to), hash (the #fragment, '' when there is none), and anchor (the element). A listener calling preventDefault() on it claims the click: the router still suppresses the browser default (a cancelled click never becomes a hard page load) and then does nothing — no pushState, no partial fetch, no intercept overlay. This is the supported way for userland to take over a link (e.g. smooth-scroll to an in-page section) instead of racing the router with a capture-phase click listener. The event does NOT fire for clicks the router ignores: modifier-key clicks, external / mailto: / tel: links, <a download>, non-_self targets, unknown routes, data-cui-rpc anchors, clicks a listener that ran first already preventDefault()ed (a listener on the anchor or any element below document runs before the router's delegated listener, and the router then leaves the click alone), and links to the current path. A link to the current path with a #fragment falls through to native hash behavior; one without a fragment, including a repeat click on a link whose navigation is still loading, is suppressed and does nothing, never a whole-document reload.

The framework's own listener on this event is the leave guard: a form marked data-hui-leave-guard with unsaved edits makes a router-intercepted link that would discard it ask first (see the attribute table), declining by calling preventDefault() — the router stands down exactly as it does for a userland listener. A link that opens an intercept layer over the form discards nothing and does not ask.

A declined link also invalidates pending navigation work, so an earlier overlay response cannot mount behind the confirmation dialog. Cancel keeps the dirty pane in place; Discard retries the original scoped move without an intervening pane changing which edits it discards. A declined close or post-save return also invalidates pending pane opens and query replies before asking. Discard closes the captured pane, not a new top layer, and a cancelled dialog preserves its original form and edits. If a page navigation is already in flight, the decline also restores its prior URL and router path and clears its navigation busy markers. Its late response cannot replace the guarded form.

Guarding departures (__gofastr.guardNavigation). gofastr:beforenavigate covers one source, a link the router takes, and only a synchronous answer. Code that has to finish something before the page goes away (flush a draft to durable storage, ask in its own dialog) registers a navigation guard. Every managed departure asks the guards before it discards anything: a link, navigate(), Back and Forward, and the intercept stack's own moves. The guards live in the navguard demand module, and nothing loads it on its own. Without it a page pays only for core's two seams and the history entry tags (below), which core writes either way.

await __gofastr.loadModule('navguard');
const stop = __gofastr.guardNavigation(async (nav) => {
  if (!editor.dirty || !nav.affects(editor.root)) return true;
  return editor.checkpoint({ signal: nav.signal }); // resolves true or false
});
// When the editor unmounts:
stop(); // safe to call more than once

• A guard returns true or undefined to allow, false to deny, or a promise of either. A throw, a rejected promise, or a returned object whose then getter throws denies; the error is logged with console.warn and reported as 'error', and a Back or Forward is put back as on any denial.
• Guards run in registration order, one at a time: a guard is asked only after every guard before it allowed, and the first denial ends the decision. Order comes from registration alone, never from listener order or from which package replaced a router property last.
• guardNavigation(fn) returns a disposer. A second call does nothing. Disposing a guard while its own answer is pending cancels the attempt: the move does not run, and the report says 'disposed'. A guard disposed before its turn is skipped; one registered during a decision is first asked on the next move.
• With no guard registered, or when every guard allows synchronously, the move runs in the same tick it did before the module existed. A move that discards nothing is not asked about: an intercept layer opening over the page, a layer refused at the stack cap, a URL-only write such as replaceURL().
• There is no timeout and no bypass. A guard that never settles keeps the page where it is until the reader makes another move, which supersedes the attempt. navigate(path, {force: true}) asks like any other navigate; force only skips the cache.

The attempt a guard receives is frozen:

History entries. Where the browser has the Navigation API, entry is the entry's key. Elsewhere it comes from the tag core writes on every history entry it makes: history.state carries __fui (the entry's id) and __fup ([numbering, position]), and entry is numbering:position:id. A push gets a new id one position past the entry it leaves, in that entry's numbering. A replace keeps the entry's id, its position and the rest of its state. When the router lands on an entry without a tag (the document's first entry, an entry that code outside the runtime wrote), it adopts it: the entry keeps its state, and its id if it has one, and starts a numbering of its own (a random number, position 0), so no position is guessed. The tags live in history.state and survive a reload. Two entries are a known distance apart only when they share a numbering. One URL can name several entries (the same page visited twice), so a guard that tracks entries compares entry, never url. Code that writes history.state itself keeps the tags by spreading the state it replaces ({...history.state, mine: 1}). A foreign push writes its own state, never a copy of core's entry tags: copying those tags would give two entries one identity.

Back and Forward under a guard. When popstate fires the browser has already moved its history, but the router has swapped nothing. A move the guards allow synchronously goes straight on. Otherwise the module undoes the traversal at once and takes the browser back to the entry the page still shows: by key with the Navigation API (navigation.traverseTo), and without it (Safari before 26.2, Firefox before 147) by history.go(-delta), the distance read off the two entries' tags. That entry returns with its own state, not as a new entry carrying a copy of its URL. The leaving page's DOM, inputs, focus and scroll stay as they were. On allow the module goes to the destination entry again (by key, or by its distance), and that landing goes on to the router, the leave guard and the intercept stack without a second ask. On denial the page stays on its own entry and the move is reported. A landing counts only on the entry the module was heading for, so a Back the reader makes meanwhile is never taken for the undo. No entry is added, dropped or rewritten, and nothing reloads. While one of the module's own traversals is in flight, a new link or navigate() is refused (reported as 'pending') and replaceURL() returns false, because a write from the wrong entry would cut off the forward history being restored; a Back or Forward made during it is overtaken by it.

When there is no known way back. The module cannot measure the move when the landing has no tag (an entry that code outside the runtime wrote), when the two entries are in different numberings (an entry the browser makes for a #fragment jump starts a numbering of its own, so a move of more than one step across it is unknown), when navigation.traverseTo throws or its commit rejects, or when a fallback history.go does not reach the entry (a few tries, 2 seconds each). Nothing is pushed and nothing is cut off then: the browser stays on the landing while the page stays on the entry it shows, with the destination's URL in the address bar while the guards decide. On allow the landing goes on to the router. On denial the module replaces that landing, and only it, with the page's URL; the landing keeps its own state and identity (it never takes the id of the page's entry), every other entry stays where it was, and the report's reason is 'unknown'. An allowed move whose destination cannot be reached after the undo has landed leaves the page where it is and also reports 'unknown'.

Inside an open intercept stack the guards are asked with intent 'overlay', and affects is true only for the layers the move closes or re-renders. A Back between layers, or back to the page under the stack, is undone the way the stack always undid one (its entries carry their positions), and the approval is bound to the entry the retry lands on, so no other landing can use it. A Back or Forward that leaves the stack for some other page (Back past the page under it to an earlier one) is asked as 'traverse' and undone and replayed like a page traversal, by key or by the tags' distance: the stack's entries carry core's tags too. A page link clicked inside the stack is asked once, before the stack walks back out of history to the page under it.

A blocked move dispatches gofastr:navigateblocked on window, with detail: {attempt, reason, error}. reason is 'denied', 'error' (a guard threw or rejected, and error holds what it threw), 'disposed', 'pending', or 'unknown' (refused with no known way back, as above; error holds a guard's throw if one caused the refusal). A superseded attempt does not report: the newer move replaced it. A denial leaves the page interactive, so a guard that wants to tell the reader why says so itself or listens for this event.

Order with the older hooks: gofastr:beforenavigate listeners, the leave guard's link ask among them, run before the guards, and so does the leave guard's ask on a data-cui-spa GET form. On Back, Forward and the stack's moves the guards run first and the leave guard after them. A leave-guard Discard makes the move again, which asks the guards again: with the kit's themed dialog a guard is asked twice about one Back the reader discards, once before the dialog and once for the replay. When the leave guard itself declines a Back or Forward, its own repair applies, as without this module: back by the distance its own tags give, or, when it has none, a push of the page's URL again.

A host shell that held a departure by wrapping _interceptPopstate or _pushURL registers a guard instead, and no package needs to replace a router property to take part. The guards see the departures those wrappers saw (Back and Forward, the stack's moves, the router's own pushes) and links and navigate() besides. They are not asked about URL-only writes, which a _pushURL wrapper also saw: pagination, deep links, X-Gofastr-Push-State, replaceURL(). A shell that rewrote the address with _pushURL(url, {replace: true}) calls replaceURL(url).

Rewriting the address (__gofastr.replaceURL(url)). Replaces the URL of the history entry the browser is on, and does nothing else: no fetch, no gofastr:navigate, no guard asked, no view transition. The page, its scroll position and focus, and the entry's id, position and every other key on its state stay; __gofastr.currentPath follows. Inside an open intercept stack the top layer's entry takes the URL and currentPath stays on the page under the stack, as for every URL write there. It returns true once written, and false, with nothing written, for a URL on another origin (a javascript: URL included), a path outside the app's base, one in another document (another locale, or a route with other document scripts), or a write the browser refuses (Safari limits how often a page may write its history). With the navguard module loaded it also returns false while a guarded Back or Forward is unresolved. A later Back or Forward from the rewritten entry is measured like any other, because it is the same entry.

Active-link highlighting. After every navigation (and at module load) the idle-loaded activelink module walks every nav a, plus any <a> carrying data-cui-match-prefix or data-cui-activelink outside a nav, with an href and tags the one matching the current path with aria-current="page" and the active class — the value is page, the ARIA-correct value for a page link, NOT true, so [aria-current="true"] selectors do not match it. A widget root announced by fui:widget-open gets the same sweep, scoped to that root: the sidebar's phone drawer is fetched after load and rendered with no current path, and no navigation follows its mount. Clearing is ownership-based: a link loses both when it carries the module's own .active class, the data-cui-activelink handover or the data-cui-match-prefix handover — those attributes are the contract by which a server-rendered first-paint mark (ui.Sidebar's CurrentPath, an exact-match aria-current) becomes activelink's to move, so a kept sidebar never shows two lit entries after a client navigation. headless.Sidebar marks every leaf data-cui-activelink because the module loads idle: a navigation can land before it ever stamped the old link, and only the handover tells it the stale mark is its own. That handover applies to navigations only: on a document that has not navigated client-side, the load-time sweep stamps matches and leaves data-cui-activelink marks alone, so the server's Active on a detail page or a URL with a query keeps its mark. A link with none of the three (pagination's aria-current="page", server breadcrumbs, hand-set state) keeps whatever it carries: the sweep sets and clears only what it owns. Marking a link current also opens its closest details[data-hui-sidebar-group] ancestor, so a collapsed sidebar group opens for its current child with no request. Left completely untouched (neither set nor cleared): href-less links (server-managed), links inside a rail nav (data-hui-rail, whose links carry .is-active, never activelink's .active, so the sweep's strip branch never touches them), and links carrying data-cui-activelink-skip (the opt-out for a current-state owned by app code or a hand-set attribute). data-cui-match-prefix opts a link into segment-prefix matching: the attribute's VALUE, when non-empty, names the prefix (a link can own a section it does not live at — framework/ui.Sidebar emits its items' MatchPath there, so a section stays lit across client navigations into it); an empty value falls back to the href. /docs lights up on /docs and /docs/getting-started, never on /docs-old.

Deferred parts announce themselves (gofastr:fill). When a route's outlet defers (app.OutletOptions.Deferred, the manifest's deferred list), its fill travels as its own part request (X-Gofastr-Part) beside the page fetch, and the runtime dispatches gofastr:fill on window once per applied part, right after its DOM lands: detail carries addr (the fill's data-cui-outlet address), path (the destination path), and t (performance.now() at apply time). A part arrives well after gofastr:navigate (which fires with the page commit), so this event is the supported hook for "the activity panel landed 700 ms later" UI — no MutationObserver heuristics. (Streaming was the old transport for this; it is gone — Chrome keeps no body in DevTools for a fetch read through a stream reader, and a navigation's requests must be inspectable.)

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

[click]
  → button has data-cui-rpc="/island/customers/page" data-cui-rpc-method="POST" data-cui-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-cui-signal="customers-rows" data-cui-signal-mode="html" gets innerHTML replaced
  → no URL change, no <main> swap, no other DOM touched

Forms

A successful RPC waits for its success toast before navigating. If the form submits again during that wait, the older request does not navigate.

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, with no special attribute and the default 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.

A form's action names a handler registered for its method, never a bare screen path. A screen answers GET and HEAD: any other method to a screen path that no route takes is a 405 with Allow: GET, HEAD (OPTIONS: 204 with the same Allow), and the screen's policy and Load never run and no session is minted. An intercepted form gets the 405 as a refusal and toasts its status. A route registered at the screen's path (r.Post("/contact", h)) wins its method; see ui-wiring → "Posting a form to a screen's own path".

Server redirects (after intercept)

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

• Location header, the runtime loads the location as a new document

(window.location.assign): the target may not be in the SPA route table, and the load resets the SSE connection the way a native form submit would. For the non-intercepted default path, redirect-following is the browser's own job, same result. That load comes after the write and does not ask the navigation guards: a guard that must run before a form leaves the page acts before the submit, not on the redirect.

An answer that is not a redirect is handled as on a data-cui-rpc form. A refusal (non-2xx) renders the server's validation envelope ({error, fields}, the one error envelope every route answers with) into the fields through the formerrors module, or toasts the status when no field matches. A 2xx answer delivers its X-Gofastr-Toast and X-Gofastr-Invalidate headers. Every intercepted submit carries the page's <meta name="csrf-token"> as X-CSRF-Token, since a JSON body has no form field for middleware.CSRF to read.

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

The redirect rule above is the intercepted plain form's (enctype="application/json", data-cui-spa), whose redirect is its post/redirect/get answer. Every other runtime fetch reads a followed redirect as no answer. fetch follows a 3xx itself, so a request whose answer was a redirect (an expired session sends it to the sign-in page) resolves with a 200 for another URL; response.redirected is the only sign. The runtime never takes that body as the request's own:

• data-cui-rpc and optimistic actions fail. No success effect runs, no success toast, no data-cui-rpc-navigate, and the response signal reads {ok: false, status: 0}. An optimistic action rolls back. A form stays where it is with what the reader typed (gofastr:formresult reports ok: false, so a leave guard keeps the form dirty) and toasts runtime.submit_failed: navigating away would throw the input away. Anything else (a button, an optimistic toggle) hands the redirect target to the client navigator, so a same-origin sign-in page opens with no reload and another origin loads as a document. Answer a successful RPC with a 2xx, never a 3xx. To move the reader after it, name the destination on the element in data-cui-rpc-navigate; the RPC path does not read X-Gofastr-Location.
• Passive fetches swap, parse and cache nothing: region and widget poll (a failed poll, so it backs off), widget chrome (a failed open) and state, widget discovery, fetchPage and server actions (empty and null), deferred parts (the slot is restored), the SSE session re-mint, and the desktop bridge (the call rejects). The embed handshake's exchange and content fetches refuse redirects outright.
• Headless behaviours follow the same rule: a sortable reorder whose commit redirects reverts, its conflict refresh mounts nothing, and a selection Copy fails.

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). An optional data-fui-plugin-fallback wrapper (from MountConfig.Fallback) holds a server-rendered node the broker shows while the frame loads and swaps back to on bootError, so a dead frame degrades to static output. 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.

Registered behaviours

A package can register its own runtime module beside its stylesheet: registry.RegisterBehavior(name, js, registry.Markers("[data-x]")). The host serves it at /__gofastr/runtime/<name>.js?v=<hash> and lists it in the module manifest; its markers reach the kernel as window.__gofastr_behaviors (from /__gofastr/manifest.js) on live pages and as the inline <script type="application/json" id="gofastr-behaviors"> block in static exports and the embed frame. The kernel scans those markers after its own table, so the module loads once when a marker appears, at boot, on DOM insertion, or after a client navigation, and data-cui-prefetch="<name>" warms it on hover. Register at package init: the host builds the behaviours block once, so RegisterBehavior panics after the host has frozen the registry (its first manifest), the same rule RegisterStyle keeps. A requirement graph the loader cannot satisfy (a cycle, an unknown module) stops a framework.App at boot (ValidateBoot); a host mounted without an App answers every request that builds the manifest (a page, /__gofastr/manifest.js) with a 500, its log line naming the cycle, never an empty manifest.

The module route (/__gofastr/runtime/<name>.js) and the compute asset route (/__gofastr/compute/<name>.js|.wasm) cache immutable only when ?v= names the bytes the process serves. Any other ?v= (a page from another replica mid-deploy, no version at all) is no-cache with the content hash as its ETag, so a browser or CDN never pins one build's bytes under another build's URL. A static export writes every registered compute asset to /__gofastr/compute/ beside the runtime modules. An exported page's head preloads the demand modules it uses except rpc.js: the static runtime answers data-cui-rpc with its stub and never loads the module. A malformed block (a window.__gofastr_behaviors that is not a descriptor map, an inline #gofastr-behaviors that is not JSON) is ignored: the kernel registers no behaviours and boots on its own module table. The catch is silent on purpose — a console.warn does not clear the core gzip budget (measured: +17 bytes at the shortest useful wording, against 8 bytes of clearance), and unlike a failed fetch the console reports nothing on its own.

An API module that page code calls, rather than one that binds markup, registers with registry.OnRequest() and no markers. It is served and listed in the module manifest like any module but left out of the marker block, and it loads only through __gofastr.loadModule(<name>) or another behaviour's registry.Requires(<name>). Because it lives in its own package, a binary that never imports that package never contains it, and a page that never asks for it never downloads it. core-ui/localdb is one.

Data such a module needs from the server rides a registered data block: registry.RegisterDataBlock("gofastr-<name>", fn) makes the host emit <script type="application/json" id="gofastr-<name>"> holding fn()'s JSON in every page head, live and exported, without importing the package. Every < in the JSON is written as \u003c, so no value can end or comment out the script. Ids the kernel or host already use (gofastr-signals, gofastr-routes, gofastr-behaviors, and the rest) are refused.

Registered markers use the package's own data- prefix; a data-cui-* marker is admitted only when the attribute is in the table above — and a data-cui-* attribute named by an interaction selector (a click's Selector, a keydown's Scope) is held to the same rule by TestInteractionSelectorsInTheTreeUseDocumentedDataFuiAttrs. The module is held to the same source lints as the kernel's own (core-ui/check: no var, no selector or storage key built from a raw value, and the rest): the clean-tree tests find every registered behaviour through its //go:embed directive. LintLegacyIdioms holds out the pre-ES2015 spellings: .push.apply (spread the list), Array.prototype.<m>.call ([...list] or Array.from), the arguments object (rest parameters) and assignments to <Ctor>.prototype (a class body). Contract and rules: core-ui/ARCHITECTURE.md "Component behaviour".

A behaviour may declare dependencies: registry.Requires("action") names the modules that must be loaded and registered before it, embedded kernel modules or other registered behaviours; the behaviours block carries them as r, and the loader honours them on every load path, requirements first, then the module's script. A name that is neither, or a cycle, panics where the block is built — at the first render that builds the manifest, not at startup (the registry is only complete once every package's init has run); through the framework's recovery middleware the panic surfaces as a 500 with the cycle path in the log line. The interaction bridge is a load path for registered behaviours too: a behaviour declares the interactions it needs retained through its module's cold-cache fetch with registry.Interactions(...) — one spec per interaction, in the bridge's own shape (Event; a click's Selector, the node resolved with closest; a keydown's Keys and Scope, a selector that must match somewhere in the document before the key is retained; a key held with Alt, Ctrl, Meta or Shift is a browser shortcut and is never retained) — the behaviours block carries them as x beside s, i and r, and the kernel installs one document-level listener per spec over the registered descriptors exactly as over its own marker table, preventing the default synchronously and replaying the event on the original node once the module registers. A behaviour that declares no interactions installs no listener and costs nothing; a malformed x field is swallowed with the rest of a broken block. An interaction selector is owned the way a marker is: one that names a data-cui-* attribute names an attribute in the table above, and a selector belongs to one behaviour — nothing refuses two descriptors that claim the same event and selector, and each of them retains and replays, so one user action arrives at both modules twice. The grammar is wider than the marker grammar, and deliberately: a marker is parsed back out of rendered HTML host-side for preload, while an interaction selector only ever reaches the browser's own querySelector and closest, so it may carry combinators, :not([attr]) and comma lists. What the browser throws on is refused at registration, because a throw inside the bridge's document-level listener kills retention silently; class and id selectors are refused too, not because they throw but because a registered module binds by attribute. Readiness is registration: the loader resolves a module's promise only when loadedModules[name] is set after its script ran — and the module sets its flag FIRST, before it installs anything (a script that failed halfway with its flag unset has its load rejected and fetched again, and the retry re-executes the file: a flag at the end leaves every listener of the first pass installed twice) — and a script that ran and never registered rejects with "module failed to register", drops its cached promise, and a retry fetches again. Preload and the static export list a needed behaviour's requirements beside it. A module with no marker (a primitive) is reachable only through Requires or an explicit loadModule; the kernel's action module is one — window.__gofastr.action.request(url, method) performs a same-origin mutation with the CSRF header and resolves to a boolean, and window.__gofastr.action.bind(el, spec) attaches the whole optimistic lifecycle (idle → pending → committed → error, the label flip, aria-busy while pending, the action:* events) to an element from a spec of endpoint, method, idle, done, group, untoggle and pressed. A bound group converges on one committed member: the revoke runs at click time and again when a commit settles, so a failed commit restores the sibling it displaced while a successful one displaces every other, and two members clicked inside one round trip still end with exactly one committed. Group members whose elements left the document are pruned on gofastr:navigate.

The framework's own headless module is registered this way by framework/headless/behavior.go, binding that package's data-hui-* hooks with the markers [data-hui-reveal], [data-hui-color], [data-hui-form-errors], [data-hui-action], [data-hui-drop], [data-hui-system], [data-hui-table] and [data-hui-selection]. Its headless-when sibling (framework/headless/when_behavior.go) binds [data-hui-when].

Host transport (window.__gofastr_transport)

Every request the runtime makes goes through window.__gofastr.fetch. It calls window.__gofastr_transport when a host installed one, and the global fetch otherwise. The slot exists for native hosts whose WebView cannot carry what fetch sends, such as a phone shell serving the app through request interception (Android drops every request body, iOS drops Blob and File bodies, and neither can return a redirect). A plain browser never sets it.

// Installed by the host, at document start or from a rail script.
window.__gofastr_transport = async (input, init) => {
  const req = new Request(input, init);
  const u = new URL(req.url);
  // Scheme and host, not .origin: a custom scheme (gofastr://app) has
  // the opaque origin "null", which every other opaque URL shares.
  if (u.protocol !== location.protocol || u.host !== location.host) return fetch(req); // input's body moved into req
  return carryOverNativeChannel(req); // must resolve to a Response
};

The runtime reads the slot each time it sends a request, so a transport installed after boot covers every later request. The transport must answer the way fetch does. After following a redirect, it reports the final address in response.url and sets response.redirected, because the runtime treats a redirected answer as no answer. A network failure rejects with a TypeError. A script of your own that should reach the app through the host calls window.__gofastr.fetch instead of fetch. The embed loader inside third-party frames is the one runtime path that keeps the global fetch. EventSource and WebSocket connections are not fetches and never reach the slot; a host serves them through its request interception, which carries a GET with no body.

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.