Principles

These principles are the most durable part of Goldar’s design. API proposals should be evaluated against them rather than preserved for their own sake.

The platform is the foundation

Goldar builds on browser and server standards:

• Links are <a href="...">.
• Mutations begin as <form method="post">.
• Views produce HTML.
• Requests and responses use Web Standards APIs.
• Browser components use Custom Elements.
• Component communication uses properties, events, children, and slots.

Goldar enhances these primitives with routing, transitions, validation, state, and type safety. It does not replace them with mandatory framework components.

An application must retain meaningful behavior when client JavaScript is unavailable. Enhancement may make navigation faster or interactions richer, but the server-rendered document remains the foundation.

Ordinary objects are the authoring model

Application concepts are represented by small classes with ordinary properties and methods:

• Route owns a URL lifecycle.
• Data owns an asynchronous read.
• Store owns interactive state.
• FormAction owns a validated mutation.
• Application composes the complete runtime.

Authors should not need reducers, dispatch functions, signal .value access, decorators, string-based dependency lookup, or a large hook vocabulary to express these concepts.

Inheritance establishes a lifecycle contract. Composition connects instances into an application graph.

Data flows down and named capabilities flow down with it

Compiled views are callable functions. Authors pass values, resources, child views, and named functions as ordinary arguments:

DashboardView({
	dashboard: this.data.dashboard,
	isSidebarOpen: this.store.isSidebarOpen,
	onToggleSidebar: () => this.store.toggleSidebar(),
});

Goldar may know that one function is a local callback and another is a server action, but both travel through view composition as named capabilities. Runtime provenance determines how each capability is delivered; the view does not reach into a global container.

The server is the default runtime

The initial response is server rendered. Data loads on the server unless a resource explicitly declares another runtime. Client JavaScript is shipped for behavior that requires it, not as an entry fee for receiving HTML.

Server-only implementations must not leak into browser bundles. The compiler is responsible for finding boundaries and producing separate server and client graphs.

Enhancement is additive

When the client runtime is present, Goldar may:

• Intercept eligible same-origin links.
• Intercept forms while preserving normal submissions as a fallback.
• Fetch the next route in the background.
• Maintain route and store lifecycles across navigation.
• Render loading, error, and revalidation states.
• Apply View Transitions where available.
• Load and register Web Components only where they are used.

The enhanced path must preserve browser expectations for modifier keys, downloads, external origins, history, focus, and scrolling.

File organization is not application semantics

A complete application may live in one file or hundreds. Core consumes an explicit object graph, not a prescribed directory tree.

The compiler may offer optional discovery conventions. Those conventions must compile to the same manifest produced by explicit registration. Moving a file must not change a URL unless filesystem routing was intentionally enabled.

No capability may require a particular folder layout.

The compiler removes work without creating a second language

The compiler may provide:

• Typed .hbs imports.
• View prop, event, and custom-element diagnostics.
• Server and browser code splitting.
• Route and component manifests.
• Reactive instrumentation.
• Lazy custom-element registration.
• Optional route discovery.

Ordinary TypeScript should remain understandable to standard tooling. Compiler behavior must be inspectable, and generated manifests should be debuggable.

Web Components are the component boundary

Goldar does not own a component class hierarchy. A custom element may use Lit, a small helper, direct HTMLElement APIs, or a future library.

Compiled views compose documents. Web Components provide encapsulated browser identity, lifecycle, and behavior where those properties are useful. Most HTML does not need to become a custom element.

Hono is infrastructure, not the application model

Hono owns HTTP concerns: middleware, routing underneath Goldar, cookies, headers, runtime bindings, streaming, errors, redirects, and deployment adapters.

Goldar owns application concerns: route lifecycle, resources, mutations, stores, views, navigation, transitions, and component loading.

Most application code should not need a Hono context. An explicit server configuration hook remains available when the application needs Hono middleware or a low-level escape hatch.

Small applications must remain small

The framework should feel proportionate. A small site should not need generated boilerplate, mandatory folders, a client router configuration file, or a dependency-injection setup.

Large applications gain structure by splitting the same concepts into modules rather than adopting a different architecture.