# Web Layer The web layer is where API drift surfaces last and costs the most turns to fix. NetScript's answer is `@netscript/fresh`: a server-first meta-framework, built on [Fresh](https://fresh.deno.dev/) 2.x and Preact, that renders pages from the **same contract object your services implement**. The page loader, the typed browser client, and the server handler share one type — so when a contract changes, the page that depends on it fails `deno check`, not production. ## The failure this layer removes Picture the usual sequence in a UI built on hand-rolled `fetch` calls. A service endpoint gains a required filter and reshapes its response. The API compiles, its tests pass, and the dashboard — which encoded the old response shape in an untyped `fetch` — keeps rendering until a user (or an agent's browser check) finds the broken page. Whoever fixes it now spends turns rediscovering what the endpoint actually returns, because nothing in the UI's code says so. In a NetScript workspace that sequence stops at the type checker. The scaffolded dashboard builds its client from the contract itself — `apps/dashboard/lib/example-service.ts` imports `UsersContractV1` and derives a typed client plus TanStack-Query factories from it — and that is the same contract object the `users` service implements. Reshape the endpoint and every page loader, island, and form that consumes it becomes a compile error with a file and line number: the response shape lives in the type system, where an agent can read it, instead of in someone's memory. ## How a page is put together You author a page with `definePage()` — binding a typed **route contract**, server **resources** and **layers** (each with its own loader, cache window, and partial-refresh endpoint), and **forms** — then build it into Fresh route wiring. Rendering is server-first: handlers run in Deno and return HTML, and only components under `islands/` ship JavaScript to the browser, where they hydrate against the same query cache the server dehydrated. ![Request flow: browser hits a Fresh route built by definePage; the server handler runs resource and layer loaders that call the typed SDK client, which calls an oRPC service backed by the database; the rendered HTML ships to the browser where an island hydrates against the same query key.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/fresh-page-model.svg) *The Fresh page model: definePage binds a route, runs server loaders through the typed SDK to a service, renders HTML, and hydrates islands against a shared query cache — one contract end to end.* Each piece of that model has its own leaf page — link into the one you need rather than reading in order: - **[The Fresh page model](https://rickylabs.github.io/netscript/web-layer/server/)** — server-first rendering, the islands boundary, and `defineFreshApp()` (`@netscript/fresh/server`), the bootstrap every NetScript Fresh app starts from. - **[The define-page builder](https://rickylabs.github.io/netscript/web-layer/builders/)** — `definePage()` and `definePartial()` (`@netscript/fresh/builders`): typed layers, defer policies, and per-layer partial refresh. - **[Request-scoped resources](https://rickylabs.github.io/netscript/web-layer/resources/)** — `withResource()`: one value resolved once per request and shared by every layer, layout, and metadata resolver on the page. - **[Layers, layout, and slots](https://rickylabs.github.io/netscript/web-layer/layers/)** — `withLayer()` and `withLayout()`: named regions that resolve concurrently, each with its own loader, fallback, and freshness window. - **[Response shaping](https://rickylabs.github.io/netscript/web-layer/response/)** — `withMeta()`, `withHeader()`, `withStatus()`, and the `GET` handler `build()` synthesises from them. - **[Route contracts](https://rickylabs.github.io/netscript/web-layer/route/)** — `defineRouteContract()`, schema helpers such as `paginationSearchSchema()` and `defineEnumPathParam()`, and the generated `routes` tree that turns a moved route file into a compile error. - **[Partials](https://rickylabs.github.io/netscript/web-layer/partials/)** — `definePartial()`, paired route references, and the layer config that turns a region into a cache-aware deferred partial. - **[Data loading & the query cache](https://rickylabs.github.io/netscript/web-layer/query/)** — `QueryIsland`, `useQuery`, `useMutation`, and `useLiveQuery`: the TanStack-Query bridge that shares one cache between server render and island hydration. - **[The query bridge](https://rickylabs.github.io/netscript/web-layer/query-bridge/)** — SDK query factories from loader to island: the two key tiers, `getCachedEntry()` as a read rather than a fetch, and when to dehydrate instead of passing `initialData`. - **[Server-validated forms](https://rickylabs.github.io/netscript/web-layer/form/)** — typed, contract-aware form handling declared as a page layer. - **[Deferred & streaming UI](https://rickylabs.github.io/netscript/web-layer/defer-streaming-ui/)** — stream a fallback now, swap in real content when a slower layer resolves. - **[Interactivity](https://rickylabs.github.io/netscript/web-layer/interactive/)** and **[durable-stream consumption](https://rickylabs.github.io/netscript/durable-workflows/streams/)** — island runtime helpers and the browser-side client for durable HTTP/SSE streams. - **[Vite integration](https://rickylabs.github.io/netscript/web-layer/vite/)**, **[testing](https://rickylabs.github.io/netscript/web-layer/testing/)**, **[diagnostics](https://rickylabs.github.io/netscript/web-layer/error/)**, and **[worked examples](https://rickylabs.github.io/netscript/web-layer/examples/)**. The visual layer on top of all of this — the copy-source component registry, design tokens, and the scaffolded dashboard app — is [Fresh UI & design](https://rickylabs.github.io/netscript/web-layer/fresh-ui/), which has its own story. ## Start here [Overview & Concepts Fresh page model Server rendering, islands, route contracts, layers, partials, and shared query cache.](https://rickylabs.github.io/netscript/netscript/web-layer/server/) [Overview & Concepts Fresh UI & design The copy-source component registry, design tokens, and the scaffolded dashboard app.](https://rickylabs.github.io/netscript/netscript/web-layer/fresh-ui/) [Quickstart Live dashboard Build a Fresh page backed by a typed SDK client and a cache-first QueryIsland.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/) [How-To Customize Fresh UI Adjust the generated UI layer and design-system surface.](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/customize-fresh-ui/) [How-To Server-validated form Build a form that validates and mutates on the server.](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/build-a-server-validated-form/) [API Reference @netscript/fresh Generated symbols for the Fresh framework package.](https://rickylabs.github.io/netscript/netscript/reference/fresh/) [API Reference @netscript/fresh-ui Generated symbols for the companion UI package.](https://rickylabs.github.io/netscript/netscript/reference/fresh-ui/) ## Learn, do, look up [Learn Live dashboard tutorial Contract to page to live stream — the web layer end to end.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/) [Do Recipes Task-oriented recipes for this area, one problem each.](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/) [Look up `@netscript/fresh` reference Generated API reference. Related units: `fresh-ui`.](https://rickylabs.github.io/netscript/netscript/reference/fresh/) [Understand Contracts & type flow The design rationale behind this pillar.](https://rickylabs.github.io/netscript/netscript/explanation/contracts/)