# Examples and sandbox

A curated index of runnable Web Layer examples built on `@netscript/fresh`. Start here when you want to see the meta-framework end to end rather than one capability at a time. Each entry below points to a tutorial or how-to that composes the documented Web Layer surface — page builders, routing, data loading, forms, and streaming UI — into something you can run.

## Where to start

The flagship example is the **live dashboard** tutorial. It walks through the full page model: defining a page with the builder, loading data through the query cache, wiring a server-validated form, and streaming deferred regions into the response. It is the most complete demonstration of how the Web Layer fits together.

- [Live dashboard tutorial](https://rickylabs.github.io/netscript/tutorials/live-dashboard/) — the end-to-end Web Layer example.

From there, the Web Layer how-to guides isolate each capability so you can lift a single pattern into your own project.

## The smallest typed example, end to end

The shortest path from a contract to a rendered island: a typed route reference, a contract-derived query, and a `QueryIsland`. It composes three documented surfaces — [routing](https://rickylabs.github.io/netscript/web-layer/route/), the [query cache](https://rickylabs.github.io/netscript/web-layer/query/), and the [SDK bridge](https://rickylabs.github.io/netscript/services-sdk/sdk/) — and nothing in it is hand-typed:

```tsx
// apps/dashboard/islands/OrdersPanel.tsx
import { QueryIsland, useIslandQuery } from "@netscript/fresh/query";
import { createRouteReference } from "@netscript/fresh/route";
import { ordersQueries } from "../lib/orders.ts";

const ordersRoute = createRouteReference("/orders");

function OrdersList() {
  const query = useIslandQuery({
    ...ordersQueries.list.queryOptions({ limit: 20 }),
    staleTime: 15_000,
  });

  return (
    <section>
      <a href={ordersRoute.href()}>Orders</a>
      <ul>
        {query.data?.map((order) => <li key={order.id}>{order.reference}</li>)}
      </ul>
    </section>
  );
}

export default function OrdersPanel() {
  return (
    <QueryIsland>
      <OrdersList />
    </QueryIsland>
  );
}
```

The `ordersQueries` factory comes from the per-service `lib/orders.ts` module the [query cache page](https://rickylabs.github.io/netscript/web-layer/query/) builds — `createServiceClient` → `createQueryFactories` — so a renamed contract field is a compile error here, not a runtime blank. For the full read/write pair (typed query plus optimistic mutation) see that page.

## The package surface

`@netscript/fresh` keeps its capabilities on explicit subpaths. The package root exposes only the cross-cutting page-loader cache helpers; everything else lives behind a dedicated import. Reading the root module is the fastest way to see how the pieces are organised before opening any one guide.

The documented subpaths are `./builders`, `./route`, `./form`, `./defer`, `./query`, `./server`, `./streams`, `./interactive`, `./vite`, `./error`, and `./testing`.

The root entry itself centres on cache projection — composing a derived cache entry from a cached list response so a detail view can reuse a list query's data without a second round trip:

```ts
import {
  hasAllCacheEntries,
  minCachedAt,
  projectCachedItemFromList,
} from "@netscript/fresh";

// `listEntry` is a cached list response loaded by a page query.
const itemEntry = projectCachedItemFromList(
  listEntry,
  (item) => item.id === selectedId,
);

// Gate rendering on every required cache entry being present.
const ready = hasAllCacheEntries([listEntry, itemEntry]);

// Oldest timestamp across the entries, for staleness display.
const oldest = minCachedAt([listEntry, itemEntry]);
```

`projectCachedItemFromList` preserves the list entry's `cachedAt` timestamp on the projected item, so the detail view stays consistent with the list it was derived from.

## API summary

| Symbol | Description |
| --- | --- |
| `hasAllCacheEntries` | Return `true` when every supplied entry is present. |
| `minCachedAt` | Return the oldest `cachedAt` timestamp across the supplied entries. |
| `projectCachedItemFromList` | Project a single cached item from a cached list response while preserving the list timestamp. |
| `CacheEntryLike` | Cached-entry shape shared by page loaders and partial orchestration. |
| `CachedListEntryLike` | Cached list-entry shape used when projecting a single list item. |

`CacheEntryLike<T>` carries a readonly `data` payload and a readonly `cachedAt` Unix-epoch timestamp in milliseconds. `CachedListEntryLike<TItem>` is the same shape over a `{ items: TItem[] }` payload.

> Hosted Sandbox Boundary
>
> Hosted, one-click playground environments (such as StackBlitz) are currently out of scope for these Web Layer examples. This design boundary allows our documentation to focus on local project and toolchain fidelity. To run these examples, clone the tutorial source repository and execute it locally using the project's build tasks. Interactive, hosted sandboxes are tracked as a future documentation experience enhancement.

## Related

[Live dashboard tutorial  The flagship end-to-end Web Layer example.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/) [The Fresh page model  How a Fresh page is shaped and served.](https://rickylabs.github.io/netscript/netscript/web-layer/server/) [Pages and the builder  Define a page with the define-page builder.](https://rickylabs.github.io/netscript/netscript/web-layer/builders/) [Routing and route contracts  Map URLs to page contracts.](https://rickylabs.github.io/netscript/netscript/web-layer/route/) [Data loading and the query cache  Load data through the page query cache.](https://rickylabs.github.io/netscript/netscript/web-layer/query/) [Server-validated forms  Validate form submissions on the server.](https://rickylabs.github.io/netscript/netscript/web-layer/form/) [Deferred and streaming UI  Stream deferred regions into the response.](https://rickylabs.github.io/netscript/netscript/web-layer/defer-streaming-ui/) [Interactive islands  Add client interactivity to a page.](https://rickylabs.github.io/netscript/netscript/web-layer/interactive/) [Build and Vite integration  The build pipeline and Vite setup.](https://rickylabs.github.io/netscript/netscript/web-layer/vite/) [Error handling and diagnostics  Surface and diagnose page errors.](https://rickylabs.github.io/netscript/netscript/web-layer/error/) [Testing Fresh pages  Test pages built with the Web Layer.](https://rickylabs.github.io/netscript/netscript/web-layer/testing/)

Return to the [Web Layer hub](https://rickylabs.github.io/netscript/web-layer/) for the full pillar overview.