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 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.

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 — server-first rendering, the islands boundary, and defineFreshApp() (@netscript/fresh/server), the bootstrap every NetScript Fresh app starts from.
• The define-page builder — definePage() and definePartial() (@netscript/fresh/builders): typed layers, defer policies, and per-layer partial refresh.
• Request-scoped resources — withResource(): one value resolved once per request and shared by every layer, layout, and metadata resolver on the page.
• Layers, layout, and slots — withLayer() and withLayout(): named regions that resolve concurrently, each with its own loader, fallback, and freshness window.
• Response shaping — withMeta(), withHeader(), withStatus(), and the GET handler build() synthesises from them.
• Route contracts — defineRouteContract(), schema helpers such as paginationSearchSchema() and defineEnumPathParam(), and the generated routes tree that turns a moved route file into a compile error.
• Partials — definePartial(), paired route references, and the layer config that turns a region into a cache-aware deferred partial.
• Data loading & the query cache — QueryIsland, useQuery, useMutation, and useLiveQuery: the TanStack-Query bridge that shares one cache between server render and island hydration.
• The 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 — typed, contract-aware form handling declared as a page layer.
• Deferred & streaming UI — stream a fallback now, swap in real content when a slower layer resolves.
• Interactivity and durable-stream consumption — island runtime helpers and the browser-side client for durable HTTP/SSE streams.
• Vite integration, testing, diagnostics, and worked 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, which has its own story.

Start here

Learn, do, look up