Documentation
¶
Overview ¶
Package runtime provides the GoFastr client-side JavaScript runtime as an embedded resource. The runtime handles event delegation, component hydration on first interaction, and SSE listeners for server-driven islands.
Use RuntimeJS() to get the JavaScript source as a string, or RuntimeSize() to check the size of the runtime.
Package runtime ships the framework's client-side JavaScript runtime.
Two surfaces are exposed:
The core runtime (`runtime.js`): the one-script substrate for SPA navigation, signals, widgets, hydration, and demand-module loading. Served at `/__gofastr/runtime.js`.
Per-module bundles (`src/<name>.js`): payloads loaded on demand via `__gofastr.loadModule(name)`. RPC is prefetched when its marker exists and awaited by the core delegation bridge; optional UI behaviors use the same loader.
The HTTP server (core-ui/widget/server.go) consumes Module(name) + ModuleNames() to wire `/__gofastr/runtime/<name>.js` routes; the uihost emits `<link rel="preload" as="script">` tags per page based on the components rendered on it.
Index ¶
- func BehaviorsJSON() []byte
- func ColorSchemeJS() (string, error)
- func DemandLoadModuleNames() []string
- func EmbedJS() (string, error)
- func EmbedLoaderJS() (string, error)
- func Module(name string) (string, bool)
- func ModuleHash(name string) string
- func ModuleNames() []string
- func ModuleSize(name string) int
- func MustEmbedJS() string
- func MustEmbedLoaderJS() string
- func MustRuntimeJS() string
- func MustStaticJS() string
- func NeededModules(pageHTML string) []string
- func RuntimeJS() (string, error)
- func RuntimeSize() int
- func StaticJS() (string, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BehaviorsJSON ¶ added in v0.86.0
func BehaviorsJSON() []byte
BehaviorsJSON returns the behaviours block the kernel reads to learn registered markers, requirements and interactions: {"<name>": {"s": ["[data-x]"], "i": true, "r": ["dep"], "x": [...]}}. Nil when nothing is registered. Live pages receive it as window.__gofastr_behaviors from /__gofastr/manifest.js; exports and the embed frame as the inline block #gofastr-behaviors — every delivery path is this one function, so a field added here reaches each of them.
func ColorSchemeJS ¶
ColorSchemeJS returns the color-scheme bootstrap script, a tiny synchronous snippet meant to ship at the TOP of <head> so dark-mode CSS tokens take effect during the same first paint that hits the page. Reads localStorage("gofastr.colorScheme") + the OS prefers-color-scheme hint, then sets <html data-color-scheme="…"> and a matching <meta name="color-scheme">.
Apps that ship a theme toggle call `window.__gofastr_colorScheme.set('auto'|'light'|'dark')` to override the OS preference.
func DemandLoadModuleNames ¶
func DemandLoadModuleNames() []string
DemandLoadModuleNames returns the unique sorted list of every module referenced by the demand-load table. Used by tests to verify every declared module actually has a corresponding src/<name>.js file.
func EmbedJS ¶ added in v0.49.0
EmbedJS returns the `embed` runtime composition, the bundle served inside an embedded surface's iframe.
Its budget is looser than the core runtime's on purpose: it loads inside a frame and blocks nothing on the host page. It is still budgeted, because how fast an embed paints is the product.
func EmbedLoaderJS ¶ added in v0.49.0
EmbedLoaderJS returns the loader a customer pastes into their own page.
This is the tightest budget in the repo: it lands on a stranger's critical path, on a site whose performance we do not control and whose owner did not choose GoFastr. It creates the iframe, hands over the nonce by postMessage, and resizes. Anything else belongs inside the frame.
func Module ¶
Module returns the source of a single split runtime module by name (e.g. "popover"). Used by the HTTP server to serve /__gofastr/runtime/<name>.js. Returns "", false when the module is not embedded. Minified on first read (cached).
func ModuleHash ¶ added in v0.86.0
ModuleHash returns the content-addressed version of a module, eight hex bytes of SHA-256 over the served bytes: what the manifest carries and the ?v= the loader appends. Empty for an unknown name.
func ModuleNames ¶
func ModuleNames() []string
ModuleNames returns the sorted list of split modules: the embedded ones and every registered behaviour. Each name maps 1:1 to a /__gofastr/runtime/<name>.js URL. A behaviour registered under an embedded module's name is refused at registration; if one slipped past (registered before this package's init reserved the names) it panics here, where the two sets meet, rather than serving one of the two in silence.
func ModuleSize ¶
ModuleSize returns the byte size of a single embedded module, or 0 if the module isn't present. Used by tests asserting per-module size budgets.
func MustEmbedJS ¶ added in v0.49.0
func MustEmbedJS() string
MustEmbedJS returns the embed runtime or panics.
func MustEmbedLoaderJS ¶ added in v0.49.0
func MustEmbedLoaderJS() string
MustEmbedLoaderJS returns the embed loader or panics.
func MustRuntimeJS ¶
func MustRuntimeJS() string
MustRuntimeJS returns the bundled runtime or panics.
func MustStaticJS ¶ added in v0.48.0
func MustStaticJS() string
MustStaticJS returns the static runtime or panics.
func NeededModules ¶
NeededModules returns the deduplicated, sorted list of demand-load runtime modules whose marker substring appears in pageHTML, plus every such module's requirements, transitively: a needed behaviour arrives with the primitive it binds through. Used by the framework's UI host to emit <link rel="preload" as="script"> tags in <head> per page, kicking off module fetches in parallel with the initial paint.
Matches are substring containment with an attribute-name boundary check, not a real HTML parse. The boundary check keeps one marker from matching inside a longer attribute name (data-fui-compute must not fire on data-fui-computed). The cost of a residual false positive is one wasted module fetch (no correctness impact). The list is sorted, not dependency-ordered: a preload link only warms a cache, and loadModule in the kernel is what orders the loads, requirements before dependents, when the marker actually appears.
func RuntimeJS ¶
RuntimeJS returns the composed runtime, the single-file IIFE every page ships by default. Assembled from the fragment files once, then minified (or returned verbatim when RUNTIME_NOMINIFY=1).
Types ¶
This section is empty.
Source Files
Directories