Execution model

Status: Design direction. Lifecycle boundaries are intentional; cache and streaming policies remain open.

Goldar has three cooperating layers:

The compiler turns templates and modules into typed server and browser graphs.
Goldar Core owns application lifecycle and rendering semantics.
Hono owns the server request pipeline.

Server request

An initial page request follows this sequence:

Hono receives a Web Standards Request.
Hono runs middleware such as logging, sessions, authentication, CSRF, and compression.
Goldar matches the request URL against the compiled route manifest.
Goldar calls the router’s createStores() factory for a fresh named store record.
Goldar passes that record to the matched route constructor as this.stores.
Route field initializers create the remainder of its Data, Store, and FormAction graph.
Goldar resolves the resources required by the returned view tree.
The renderer converts the view tree into HTML or a stream.
Hono returns the resulting Response.

The route graph and its named store record are request-local. A store created by createStores() or as a route field must never become a process-global singleton on the server. A later HTTP request receives a new record; durable state belongs in an explicit persistence mechanism.

Data resolution

A Data instance behaves like a resource state machine:

idle -> loading -> data
               -> error

data -> revalidating -> data
                     -> error with stale data

Within one resolution scope, repeated reads of the same resource instance share one pending operation. Goldar passes an AbortSignal to loads so abandoned navigation can cancel work when the underlying API supports cancellation.

Cross-request caching is separate from request deduplication. A cache policy must define:

The cache scope.
The cache key.
Freshness and expiration.
Whether stale data may be rendered during revalidation.
Which mutations invalidate the entry.

Until those semantics are fixed, documentation must not imply that request deduplication is durable caching.

Async rendering

AsyncView represents a resource-dependent portion of a view tree. It allows one authoring shape to support multiple rendering strategies.

For blocking SSR, Goldar waits for the resource and renders data or error.

For streaming SSR, Goldar may render loading, flush the surrounding document, and later stream the resolved state.

During client navigation, Goldar may render loading while fetching the next route.

During refresh, Goldar may render revalidating with the previous value so the interface does not unnecessarily disappear.

The application should not have to rewrite its route for each strategy. Deployment and route policy determine the strategy.

Navigation begins with an ordinary link:

<a href="/posts/42">Read post</a>

Without client JavaScript, the browser performs a normal document navigation.

When the Goldar navigator is active, it may intercept an eligible same-origin click, fetch the next route, update history, replace the relevant outlet, restore focus and scrolling, and apply a View Transition.

The navigator must not intercept navigation when native behavior is requested or expected, including:

External origins.
Modifier-key clicks.
Non-default mouse buttons.
target attributes.
Downloads.
Hash-only navigation.
Links explicitly marked for a document reload.

Programmatic navigation exists as an escape hatch, not the primary template abstraction.

Form submission

Mutations begin with an ordinary form POST:

<form method="post">
	<input name="title">
	<button name="_goldar_action" value="create-post">Create post</button>
</form>

Hono receives the submission and runs security middleware. Goldar identifies the route-local action, validates input, runs the mutation, and produces one of the following outcomes:

A redirect.
A rendered validation failure.
A successful rendered response.
An enhanced-navigation result that causes resource revalidation.

The enhanced path must preserve the same domain behavior and validation semantics as the document-submission path.

Client lifecycle

Client JavaScript is generated from capabilities used by the rendered application rather than from the mere presence of a route.

The client graph may contain:

The navigation runtime.
Store behavior used by hydrated views.
Local callback closures.
Web Component implementations.
Async resource state needed for refresh or client navigation.

Server-only Data.load() and FormAction.submit() implementations remain in the server graph unless explicitly declared client-capable.

Web Component lifecycle

HTML containing an unknown custom-element name is valid before its implementation loads. The server can render the element and its children immediately.

The compiler emits registration chunks for custom elements used by the route. When a chunk loads, it registers the implementation with customElements.define() and the browser upgrades matching elements.

Loading policy may be eager, idle, visible, interaction-triggered, or explicitly configured. The element implementation owns its browser lifecycle after registration.

Errors

Errors belong to the narrowest meaningful boundary:

AsyncView.error handles a resource failure.
A route error boundary handles failures constructing or rendering that route.
The application error boundary handles uncaught failures.
Hono handles the final HTTP error response and logging integration.

Development responses should identify the owning route, resource, view, or action. Production responses must avoid exposing secrets or internal stack traces.

Deployment

Hono allows the same generated server application to target runtimes that implement standard request and response primitives. Runtime adapters remain responsible for deployment-specific concerns such as bindings, filesystem access, streaming support, and asset serving.

Goldar should not pretend those runtimes are identical. Platform-specific capabilities are exposed through an explicit platform context or server configuration rather than silently becoming globals.