toiljs 0.0.116 → 0.0.118

package/docs/frontend/toil-global.md

@@ -1,216 +0,0 @@
-# The Toil global (reference)
-
-Almost the entire toiljs client API hangs off one global object, `Toil`, so your route files need no imports for the everyday things. This page is the full index: every `Toil.*` member, its TypeScript signature, and a one-line description, grouped by area. Reach for it when you know roughly what you want and just need the exact name or shape; the deeper guides (linked per section) explain the concepts.
-
-`Toil` is not a hand-written object. It is the module namespace of the `toiljs/client` package, exposed as a global. The compiler writes a `toil-env.d.ts` at your project root containing `declare const Toil: typeof import('toiljs/client')`, so `Toil` is typed as the whole package and every member autocompletes with no import. Put another way: anything you could `import { X } from 'toiljs/client'` is reachable as `Toil.X`.
-
-A few members are also bare globals, handed to you the same way. `Server` (the typed backend client) and `parseError` are global on their own and additionally live under `Toil` (so `Server` and `Toil.Server` are the same value, likewise `parseError`). `FastMap`, `FastSet`, `DataWriter`, and `DataReader` (the fast collections and compact binary codec from `toiljs/io`, see [Data types](../backend/data.md)) are bare globals only: they are not under `Toil`, so write `new DataWriter()`, never `new Toil.DataWriter()`.
-
-## Components (JSX)
-
-Drop-in components you render in JSX. See [Images](./images.md), [Scripts](./scripts.md), [Fetching data](./data-fetching.md), and [Metadata and SEO](./metadata.md) for the detail.
-
-| Member | Signature | Description |
-| --- | --- | --- |
-| `Toil.Image` | `Image(props: ImageProps): ReactNode` | A drop-in `<img>` that reserves space (no layout shift), lazy-loads, and can fade in from a blur placeholder. See [Images](./images.md). |
-| `Toil.Script` | `Script(props: ScriptProps): ReactNode` | Loads an external or inline `<script>` with a load `strategy`, deduplicated so it runs at most once. Renders nothing. See [Scripts](./scripts.md). |
-| `Toil.Form` | `Form(props: FormProps): ReactNode` | A `<form>` that runs an action on submit (no reload) and revalidates loader data on success. See [Fetching data](./data-fetching.md). |
-| `Toil.Slot` | `Slot(props: SlotProps): ReactNode` | Renders the parallel-route slot named `props.name` (`{ name: string; fallback?: ReactNode }`) for the current URL. See [Routing](./routing.md). |
-| `Toil.Head` | `Head(props: HeadSpec): null` | Declarative form of `useHead`: `<Toil.Head title="..." meta={[...]} />`. Renders nothing. See [Metadata and SEO](./metadata.md). |
-| `Toil.Metadata` | `Metadata(props: Metadata): null` | Declarative form of `useMetadata`: `<Toil.Metadata title="..." openGraph={...} />`. Renders nothing. See [Metadata and SEO](./metadata.md). |
-| `Toil.Router` | `Router(props: { routes; layout?; notFound?; globalError?; slots? }): ReactNode` | The app router element. `Toil.mount` renders this for you, so you rarely use it directly. |
-
-## SSR marker primitives
-
-These mark a route's dynamic bits so the edge can server-render it (the compiler's template extractor finds them deterministically). They are transparent at runtime: in the browser they render exactly the normal tree. See [Components](./components.md) and [Rendering and SSR](./rendering.md).
-
-| Member | Signature | Description |
-| --- | --- | --- |
-| `Toil.Hole` | `Hole(props: HoleProps): ReactNode` | A scalar text hole (`{ id: string; children?: ReactNode }`); renders `children` in the browser, a text insertion point under the SSR extractor. |
-| `Toil.Repeat` | `Repeat<T>(props: RepeatProps<T>): ReactNode` | A repeat region (`{ id; each: readonly T[]; children: (item: T, index: number) => ReactNode }`); `each.map(children)` in the browser. |
-| `Toil.RawHtml` | `RawHtml(props: RawHtmlProps): ReactNode` | A raw-HTML block hole (`{ id; html; as? }`); wraps `dangerouslySetInnerHTML` in a host element (default `div`). |
-| `Toil.attr` | `attr(id: string, value: string): string` | An attribute-value hole, used in attribute position (`href={Toil.attr('u', d.url)}`); returns `value` unchanged in the browser. |
-| `Toil.Island` | `Island(props: IslandProps): ReactNode` | A client-only escape hatch (`{ children? }`); renders nothing on the server and first paint, then reveals `children` after mount (so no SSR / SEO, by design). |
-
-## Navigation
-
-Client-side links and imperative navigation. Detailed guide: [Navigation](./navigation.md).
-
-| Member | Signature | Description |
-| --- | --- | --- |
-| `Toil.Link` | `Link(props: LinkProps): ReactNode` | A client-side navigation `<a>`: no full reload, prefetches on hover/focus, falls through to the browser for external / `target` / `download` / `#hash` links. |
-| `Toil.NavLink` | `NavLink(props: NavLinkProps): ReactNode` | A `Link` that adds an active class (default `"active"`) and `aria-current="page"` when it points at the current page. |
-| `Toil.matchActive` | `matchActive(linkPath: string, currentPath: string, end: boolean): boolean` | Whether a link to `linkPath` is active for `currentPath` (the pure rule behind `NavLink`). |
-| `Toil.navigate` | `navigate(href: Href, options?: NavigateOptions): void` | Navigate in code (no hook needed), pushing history or replacing with `{ replace: true }`. |
-| `Toil.back` | `back(): void` | Go back one history entry. |
-| `Toil.forward` | `forward(): void` | Go forward one history entry. |
-| `Toil.refresh` | `refresh(): void` | Re-render the current route and re-run its loader (its `loading.tsx` shows while it re-fetches). |
-| `Toil.href` | `href(path: string): Href` | Assert a runtime-built string is a valid `Href`. Escape hatch for a path assembled from data. |
-| `Toil.prefetch` | `prefetch(href: string): void` | Warm a route's chunk ahead of navigation; a no-op for external, unknown, or already-warmed targets. |
-| `Toil.setViewTransitions` | `setViewTransitions(enabled: boolean): void` | Enable animated View Transitions for navigation (normally set once from `client.viewTransitions`). |
-| `Toil.setTransitions` | `setTransitions(enabled: boolean): void` | Keep the current page visible until the next route is ready (normally set once from `client.transitions`). |
-
-## Routing and location hooks
-
-Hooks a component uses to read where it is and to get a router handle.
-
-| Member | Signature | Description |
-| --- | --- | --- |
-| `Toil.useParams` | `useParams<T extends RouteParams = RouteParams>(): T` | Read the dynamic route params, e.g. `{ id }` for `/blog/[id]`. Values are always strings. |
-| `Toil.useNavigate` | `useNavigate(): (href: Href, options?: NavigateOptions) => void` | Returns the bare `navigate` function. |
-| `Toil.useRouter` | `useRouter(): RouterInstance` | Returns the router handle (`push` / `replace` / `back` / `forward` / `refresh` / `revalidate` / `prefetch`). |
-| `Toil.useLocation` | `useLocation(): string` | The current pathname, re-read on each navigation (an alias of `usePathname`). |
-| `Toil.usePathname` | `usePathname(): string` | The current pathname, e.g. `"/blog/42"`. |
-| `Toil.useSearchParams` | `useSearchParams(): URLSearchParams` | The query string as a `URLSearchParams`, re-read on each navigation. |
-| `Toil.useNavigationPending` | `useNavigationPending(): boolean` | `true` while a navigation is in flight (drives a top loading bar). |
-| `Toil.matchRoute` | `matchRoute(pattern: string, pathname: string): RouteParams \| null` | Pure route matcher: extract params, or `null` if the pattern does not match. |
-
-## Route data and mutations
-
-Loaders read data on navigation, actions write it. See [Fetching data](./data-fetching.md).
-
-| Member | Signature | Description |
-| --- | --- | --- |
-| `Toil.useLoaderData` | `useLoaderData<L extends LoaderFunction>(loader: L): Awaited<ReturnType<L>>` | Read the data the current route's `loader` returned. Passing `loader` infers the type; the no-arg `useLoaderData<T>()` returns `unknown` unless you supply `T`. |
-| `Toil.revalidate` | `revalidate(href?: string): void` | Invalidate loader data and re-render so the active route (or a given href) re-fetches. Call after a mutation; usable outside React. |
-| `Toil.invalidateLoaderData` | `invalidateLoaderData(href?: string): void` | Drop cached loader data (all routes, or one href) without re-rendering. |
-| `Toil.useAction` | `useAction<TInput = void, TData = unknown>(fn: (input: TInput) => TData \| Promise<TData>, options?: UseActionOptions<TData>): ActionHandle<TInput, TData>` | Run a mutation with pending / error / result tracking; revalidates loader data on success. |
-
-## Head and metadata
-
-Set the document `<head>` from a component or resolve a route's metadata. See [Metadata and SEO](./metadata.md).
-
-| Member | Signature | Description |
-| --- | --- | --- |
-| `Toil.useHead` | `useHead(spec: HeadSpec): void` | Apply a title / `<meta>` / `<link>` contribution for the component's lifetime (reverts on unmount, composes across the tree). |
-| `Toil.useTitle` | `useTitle(title: string): void` | Set `document.title` for the component's lifetime. |
-| `Toil.mergeHead` | `mergeHead(specs: readonly HeadSpec[]): ResolvedHead` | Merge head specs in order: the last `title` wins, `meta` dedupes by name/property, `link` by rel+href. |
-| `Toil.useMetadata` | `useMetadata(metadata: Metadata): void` | Apply a route-style `Metadata` object from inside any component (the runtime counterpart of a route's `metadata` export). |
-| `Toil.resolveMetadata` | `resolveMetadata(metadata: Metadata): HeadSpec` | Expand a `Metadata` object into a title plus concrete `<meta>` / `<link>` tags. |
-
-## Page search
-
-Query the statically-baked index of your pages' metadata. See [Search](./search.md).
-
-| Member | Signature | Description |
-| --- | --- | --- |
-| `Toil.searchPages` | `searchPages(query: string, options?: PageSearchOptions): PageSearchResult[]` | Rank the registered page index against a query (pure, framework-agnostic; AND semantics across terms). |
-| `Toil.usePageSearch` | `usePageSearch(query: string, options?: PageSearchOptions): PageSearch` | React binding for `searchPages`, memoized, with a `goTo` helper that navigates to a match. |
-| `Toil.registerPages` | `registerPages(pages: readonly PageMeta[]): void` | Replace the live page index. Called once at startup by the generated bundle; rarely called by user code. |
-| `Toil.getPages` | `getPages(): readonly PageMeta[]` | The registered page index (every page, including dynamic ones). Empty before registration. |
-| `Toil.pagePath` | `pagePath(target: string \| PageMeta \| PageSearchResult): string` | Normalize a result / page / raw path to its route path string. |
-
-## Realtime
-
-Open a channel or a typed stream to the backend. See [Channels](../realtime/channels.md) and [Streams](../realtime/streams.md).
-
-| Member | Signature | Description |
-| --- | --- | --- |
-| `Toil.connectChannel` | `connectChannel(onMessage: (data: ChannelData) => void, options?: ChannelOptions): Channel` | Open a WebSocket channel to the backend, invoking `onMessage` per frame; returns `send` / `close`. |
-| `Toil.useChannel` | `useChannel(options?: ChannelOptions): ChannelHook` | React hook over `connectChannel`: connects on mount, tracks `connected` + `messages`, exposes `send`. |
-| `Toil.resolveChannelUrl` | `resolveChannelUrl(path?: string, location?: { protocol: string; host: string }): string` | Derive the channel's `ws(s)://` URL from the current page location. |
-| `Toil.makeStreamClient` | `makeStreamClient(routes: Record<string, string>, origin?: string, encoders?: Record<string, (msg: never) => Uint8Array>): StreamClient` | Build the `Server.Stream` client from the generated route map. Used by generated code; rarely called directly. |
-
-## Backend client, errors, bootstrap
-
-| Member | Signature | Description |
-| --- | --- | --- |
-| `Toil.Server` | `Server.REST.<controller>.<route>(args)` / `Server.Stream.<class>.connect(path?)` / `Server.<service>.<method>(args)` | The typed backend surface. Its shape is generated into `shared/server.ts`; this global is the runtime behind it. See [Fetching data](./data-fetching.md). |
-| `Toil.parseError` | `parseError(err: unknown): string` | Extract a human-readable message from an unknown thrown value: `Error.message`, else `String(err)`. |
-| `Toil.mount` | `mount(routes: RouteDef[], layout?: LayoutLoader, notFound?: NotFoundLoader, globalError?: ErrorComponentLoader, slots?: Record<string, RouteDef[]>): void` | Boot the app into `#root` and start idle link prefetching. Called by the generated entry file; you rarely call it yourself. |
-
-## Auth
-
-The whole password-auth client lives under `Toil.Auth`, and its error family is exposed on `Toil.*` (and mirrored under `Toil.Auth.*`) so you can branch on it. The password never leaves the browser. See [Auth](../auth/README.md).
-
-| Member | Signature | Description |
-| --- | --- | --- |
-| `Toil.Auth.register` | `register(username: string, password: string, email: string, opts?: AuthOptions): Promise<void>` | Create an account (only a derived public key is ever sent). Throws `UsernameTakenError` / `EmailInUseError` on conflict. |
-| `Toil.Auth.login` | `login(username: string, password: string, opts?: AuthOptions): Promise<Uint8Array>` | Log in with mutual authentication; resolves to the opaque session token. |
-| `Toil.Auth.confirmEmail` | `confirmEmail(token: string, opts?: AuthOptions): Promise<void>` | Confirm an account from the one-time token in the emailed link. |
-| `Toil.Auth.resendConfirmation` | `resendConfirmation(email: string, opts?: AuthOptions): Promise<void>` | Ask the server to re-send the confirmation email (never reveals whether the address exists). |
-| `Toil.Auth.requestPasswordReset` | `requestPasswordReset(email: string, opts?: AuthOptions): Promise<void>` | Begin a password reset by emailing a link (anti-enumeration: always resolves). |
-| `Toil.Auth.resetPassword` | `resetPassword(token: string, newPassword: string, opts?: AuthOptions): Promise<void>` | Complete a reset from the token plus a new password. |
-| `Toil.Auth.verifyTwoFactor` | `verifyTwoFactor(twoFaId: string, code: string, opts?: AuthOptions): Promise<Uint8Array>` | Finish a 2FA login by submitting the code for `twoFaId`; resolves to the session token. |
-| `Toil.Auth.setupTwoFactor` | `setupTwoFactor(method: number, opts?: AuthOptions): Promise<void>` | Begin enabling or disabling 2FA for the current session user (pass a `TwoFactorMethod` value). |
-| `Toil.Auth.confirmTwoFactorSetup` | `confirmTwoFactorSetup(code: string, opts?: AuthOptions): Promise<void>` | Confirm a pending `setupTwoFactor` with the delivered code. |
-| `Toil.Auth.twoFactorStatus` | `twoFactorStatus(opts?: AuthOptions): Promise<number>` | The current user's 2FA method (a `TwoFactorMethod` value; `0` means off). |
-| `Toil.Auth.TwoFactorMethod` | `{ None: 0, Email: 1 }` | The 2FA method values, mirroring the server enum. |
-
-The typed error surface (each error carries a stable `code`, and every subclass maps 1:1 to an `AuthErrorCode`):
-
-| Member | Signature | Description |
-| --- | --- | --- |
-| `Toil.AuthError` | `class AuthError extends Error { readonly code: AuthErrorCode }` | Base class for every auth error. `err instanceof Toil.AuthError` narrows the whole family; `err.code` discriminates within it. |
-| `Toil.AuthErrorCode` | `enum AuthErrorCode` (string values) | The stable, machine-readable discriminant carried as `err.code`. Branch on this, never on `err.message` or `err.name`. |
-| `Toil.UsernameTakenError` | `class UsernameTakenError extends AuthError` | register: the username is already registered (`AuthErrorCode.UsernameTaken`). |
-| `Toil.EmailInUseError` | `class EmailInUseError extends AuthError` | register: the email is already in use (`AuthErrorCode.EmailInUse`). |
-| `Toil.InvalidCredentialsError` | `class InvalidCredentialsError extends AuthError` | login: wrong username or password (`AuthErrorCode.InvalidCredentials`). |
-| `Toil.EmailNotConfirmedError` | `class EmailNotConfirmedError extends AuthError` | login: valid credential, but the email is not confirmed (`AuthErrorCode.EmailNotConfirmed`). |
-| `Toil.TwoFactorRequiredError` | `class TwoFactorRequiredError extends AuthError { readonly twoFaId: string }` | login: a second factor is required; echo `err.twoFaId` to `verifyTwoFactor` (`AuthErrorCode.TwoFactorRequired`). |
-| `Toil.ServerAuthFailedError` | `class ServerAuthFailedError extends AuthError` | login/2fa: the server failed to prove its identity, possible MITM (`AuthErrorCode.ServerAuthFailed`). |
-| `Toil.TwoFactorCodeError` | `class TwoFactorCodeError extends AuthError` | 2fa: the code was wrong, expired, or already used (`AuthErrorCode.TwoFactorCodeInvalid`). |
-| `Toil.ConfirmationInvalidError` | `class ConfirmationInvalidError extends AuthError` | confirm: the confirmation link was invalid or expired (`AuthErrorCode.ConfirmationInvalid`). |
-| `Toil.PasswordResetInvalidError` | `class PasswordResetInvalidError extends AuthError` | reset: the reset link was invalid or expired (`AuthErrorCode.PasswordResetInvalid`). |
-
-The `AuthErrorCode` string values:
-
-```ts
-enum AuthErrorCode {
-  RequestFailed = 'request_failed',
-  ProtocolError = 'protocol_error',
-  UsernameTaken = 'username_taken',
-  EmailInUse = 'email_in_use',
-  RegistrationRejected = 'registration_rejected',
-  InvalidCredentials = 'invalid_credentials',
-  EmailNotConfirmed = 'email_not_confirmed',
-  TwoFactorRequired = 'two_factor_required',
-  ServerAuthFailed = 'server_auth_failed',
-  TwoFactorCodeInvalid = 'two_factor_code_invalid',
-  TwoFactorSetupFailed = 'two_factor_setup_failed',
-  ConfirmationInvalid = 'confirmation_invalid',
-  PasswordResetInvalid = 'password_reset_invalid',
-}
-```
-
-Catch by class for the common branches, or on `err.code` for a precise check:
-
-```tsx
-try {
-  const token = await Toil.Auth.login(username, password);
-  // ... persist the session token and redirect
-} catch (err) {
-  if (err instanceof Toil.EmailNotConfirmedError) return promptEmailConfirmation();
-  if (err instanceof Toil.TwoFactorRequiredError) return promptTwoFactorCode(err.twoFaId);
-  if (err instanceof Toil.AuthError && err.code === Toil.AuthErrorCode.InvalidCredentials) {
-    return setError('Incorrect username or password.');
-  }
-  throw err;
-}
-```
-
-## A note on types
-
-Every member above is a value, and values on `Toil.*` need no import: `Toil.Link`, `Toil.useParams`, `Toil.Auth.login`. Types are different. In type position, only a small set are namespaced as `Toil.<Type>`, because the generated `toil-env.d.ts` aliases exactly these under a `declare namespace Toil` block:
-
-`LoaderArgs`, `LoaderFunction`, `Revalidate`, `Metadata`, `GenerateMetadata`, `GenerateStaticParams`, `StaticParams`, `RouteErrorProps`, `Href`, `RoutePath`, `PageMeta`, `SearchHints`.
-
-So a loader can annotate its argument with no import:
-
-```tsx
-export const loader = async ({ params }: Toil.LoaderArgs) => { /* ... */ };
-```
-
-Every other exported type (for example `LinkProps`, `NavLinkState`, `NavigateOptions`, `RouterInstance`, `ImageProps`, `ScriptProps`, `FormProps`, `ActionState`) is not in that namespace, so it must be imported from the package:
-
-```tsx
-import type { ImageProps } from 'toiljs/client';
-```
-
-## Related
-
-- [Navigation](./navigation.md): links, active state, and navigating in code.
-- [Components](./components.md): the built-in components and the SSR marker primitives.
-- [Fetching data](./data-fetching.md): the `Server` client, loaders, actions, and forms.
-- [Metadata and SEO](./metadata.md): titles, descriptions, and social-share tags per route.
-- [Auth](../auth/README.md): the full password-auth client and its error handling.

package/docs/getting-started/README.md

@@ -1,81 +0,0 @@
-# Getting started
-
-toiljs is a full-stack web framework: you write a React frontend and a TypeScript backend in one project, and toiljs ships both together. This section takes you from "nothing installed" to "a small feature running end to end."
-
-## What toiljs is
-
-Think of a normal web app as two programs that have to agree with each other:
-
-- A **frontend**: the React code that runs in your user's browser.
-- A **backend**: the code that runs on a server, answers requests, and talks to a database.
-
-Normally these live in separate projects, speak to each other over hand-written HTTP calls, and drift apart until something breaks at runtime. toiljs puts both in one repository and wires them together with types, so a change on one side shows up as a compile error on the other side instead of a bug in production.
-
-The twist is what your backend becomes. You write it in TypeScript, but toiljs does not run it in Node.js. Instead, a compiler called **toilscript** turns your backend into **WebAssembly** (often shortened to "Wasm"): a small, fast, sandboxed program that runs at the **edge**. "Edge" just means servers spread all over the world, close to your users, so requests do not have to travel to one far-away data center. A worldwide database called **ToilDB** is built in, so you can store and read data without setting up or connecting to a database yourself.
-
-New terms, defined once:
-
-- **WebAssembly / Wasm**: a compact binary format that runs code in a locked-down sandbox at near-native speed. Your backend compiles to a single `.wasm` file.
-- **toilscript**: the compiler that turns your TypeScript backend into that `.wasm` file. It accepts a strict subset of TypeScript (more on that below).
-- **Dacely edge**: the global network of servers that runs your `.wasm` backend.
-- **ToilDB**: the built-in database that lives on the edge next to your code.
-
-## The client / server / shared mental model
-
-Every toiljs project is organized into three folders. The most important thing to learn first is **where each piece of code actually runs**.
-
-```mermaid
-flowchart LR
-    A["Your project<br/>(one repo)"] -->|toiljs build| B["client bundle<br/>React + JS"]
-    A -->|toilscript compiles| C["server.wasm<br/>your backend"]
-    B --> U["User's browser"]
-    C --> E["Dacely edge<br/>(worldwide servers)"]
-    E --> D[("ToilDB<br/>global database")]
-    U <-->|"HTTP / realtime"| E
-```
-
-- **`client/`** is your React app: pages, components, and styles. It is bundled by [Vite](https://vitejs.dev) and runs **in the browser**.
-- **`server/`** is your backend: HTTP routes, database access, auth. It is compiled by toilscript to `build/server/release.wasm` and runs **on the edge** (and locally when you run the dev server).
-- **`shared/`** holds a file that toiljs **generates for you** (`shared/server.ts`). It is a fully typed client: the browser calls your backend through a `Server` object, and TypeScript checks every call. You do not write this file by hand.
-
-Here is the loop in one picture:
-
-```mermaid
-flowchart TD
-    W["client/routes/page.tsx<br/>(browser)"] -->|"Server.REST.likes.like()"| G["shared/server.ts<br/>(generated typed client)"]
-    G -->|"HTTP request"| S["server/routes/Likes.ts<br/>(your @rest route, in wasm)"]
-    S -->|"read / write"| DB[("ToilDB")]
-    S -->|"typed response"| W
-```
-
-You write both ends in TypeScript, and the generated `shared/server.ts` in the middle keeps them in sync.
-
-## Two rules to keep in mind
-
-These two facts explain most of how toiljs backends behave. They are covered in depth later, but it helps to meet them now.
-
-1. **The server runs one fresh instance per request.** Every request gets a brand-new copy of your `.wasm`, and its memory is wiped when the request ends. So a normal variable you set in one request is gone by the next request. Anything that must survive (accounts, counters, posts) has to go into **ToilDB** or another store. Nothing in a plain module-level variable persists.
-
-2. **The server is not Node.js.** toilscript compiles a strict subset of TypeScript, so you cannot `import` an arbitrary npm package into `server/` or use Node APIs like `fs`. Instead, toiljs gives you built-in globals for the common needs: `crypto`, cookies, email, the database, and more. See [Types](../concepts/types.md) and [Decorators](../concepts/decorators.md) for the details.
-
-The client side, by contrast, is normal React. You can use React libraries and browser APIs there as usual.
-
-## The getting-started path
-
-Work through these pages in order:
-
-1. **[Installation](./installation.md)**: check your Node.js version and install the toiljs command-line tool.
-2. **[Create a project](./create-project.md)**: scaffold a new app and see what you get.
-3. **[Project structure](./project-structure.md)**: a tour of every folder and file, and where each one runs.
-4. **[Your first app](./first-app.md)**: build a tiny feature end to end, a page that calls a backend route and reads and writes one piece of ToilDB data.
-5. **[Migrating an existing app](./migrating.md)**: bring a React app you already have into toiljs.
-6. **[Deploy](./deploy.md)**: build for production and self-host it, and how the managed edge fits in.
-
-## Related
-
-- [Documentation home](../README.md)
-- [The CLI reference](../cli/README.md)
-- [Frontend overview](../frontend/README.md)
-- [Backend overview](../backend/README.md)
-- [Database overview](../database/README.md)
-- [Compute tiers (where code runs)](../concepts/tiers.md)

package/docs/getting-started/create-project.md

@@ -1,131 +0,0 @@
-# Create a project
-
-Scaffold a brand-new toiljs app with one command. The CLI asks a few questions, writes the files, and (optionally) installs dependencies for you.
-
-## Why and when
-
-`toiljs create` is how every project starts. It wires up the enforced toiljs presets (TypeScript, ESLint, and Prettier config), the file-based routing, and a working client and server, so you get a project that builds and runs on the first try. Use it for a new app. To bring an **existing** React app into toiljs instead, see [Migrating](./migrating.md).
-
-## The command
-
-```sh
-toiljs create my-app
-```
-
-Replace `my-app` with your project name (it becomes the folder name). If you leave the name off, the wizard asks for one.
-
-By default this runs an interactive wizard. To skip every question and accept the defaults (handy for scripts and CI), add `--yes`:
-
-```sh
-toiljs create my-app --yes
-```
-
-## What the wizard asks
-
-Running `toiljs create` walks you through these prompts. Each one has a flag you can pass instead, so you can answer some or all of them up front.
-
-| Prompt | What it decides | Flag | Default |
-| --- | --- | --- | --- |
-| Project name | The folder and package name | (the first argument) | `my-toil-app` |
-| Which template? | How much starter code you get | `-t, --template <app\|minimal>` | `app` |
-| Styling | The CSS flavor for `client/` | `--style <css\|sass\|less\|stylus>` | `css` |
-| Add Tailwind CSS? | Adds Tailwind on top of the styling | `--tailwind` / `--no-tailwind` | off |
-| AI assistant files | Editor hint files for Claude, Cursor, Codex, Copilot | `--no-ai` (to skip) | all |
-| Optimize images at build time? | Resize and compress imported images | `--images` / `--no-images` | on |
-| Initialize a git repository? | Runs `git init` and stages the files | `--git` / `--no-git` | on |
-| Install dependencies now? | Runs your package manager's install | `--install` / `--no-install` | on |
-
-Two more flags do not have a prompt:
-
-- `--pm <npm\|pnpm\|yarn\|bun>` picks the package manager to install with (default `npm`).
-- `-y, --yes` accepts every default and runs without any prompts.
-
-### The two templates
-
-- **`app`** (default) is the full starter: a landing page, a shared layout, styles, and a set of demo routes that show off HTTP routes, typed RPC, cookies, auth, and a ToilDB-backed guestbook. Great for learning by reading real, working code.
-- **`minimal`** is the bare minimum: a layout, a single home page, and a tiny server handler with one example endpoint. Great when you want a clean slate.
-
-A fully non-interactive example:
-
-```sh
-toiljs create my-app --yes --template minimal --style css --no-tailwind --pm pnpm
-```
-
-## What gets scaffolded
-
-Here is the shape of a new **`app`** project. The exact set of demo routes may grow over time, so this is trimmed for readability.
-
-```text
-my-app/
-  package.json            scripts + dependencies (toiljs, react, toilscript, ...)
-  toil.config.ts          client/build config (SEO, images, page transitions)
-  toilconfig.json         server (wasm) build config for toilscript
-  tsconfig.json           TypeScript config for the client
-  eslint.config.js        linting preset
-  .prettierrc             formatting preset
-  .gitignore              ignores build output, generated files, and .env files
-  toil-env.d.ts           generated editor types for client globals (Toil.*)
-  toil-routes.d.ts        generated typed-route names (filled in on first build)
-  README.md
-  CLAUDE.md / AGENTS.md   AI assistant hint files (if you kept them)
-
-  client/                 your React app (runs in the browser)
-    toil.tsx              the client entry: mounts routes + layout
-    layout.tsx            the root layout that wraps every page
-    404.tsx               the not-found page
-    global-error.tsx      the top-level error page
-    routes/               file-based pages (index.tsx = "/", about.tsx = "/about", ...)
-    components/           shared React components
-    styles/main.css       global styles
-    public/               static files served as-is (favicon, robots.txt, images)
-
-  server/                 your backend (compiled to wasm, runs on the edge)
-    main.ts               the entry: wires the handler + imports your surface modules
-    tsconfig.json         server-only TS config (loads the toilscript editor plugin)
-    toil-server-env.d.ts  generated editor types for server globals (Cookie, crypto, ...)
-    core/                 your top-level request handler and shared logic
-    models/               @data classes (the typed wire types)
-    routes/               @rest controllers (HTTP endpoints)
-    services/             @service classes and @remote functions (typed RPC)
-    migrations/           ToilDB schema migrations (README explains the convention)
-    scheduled/            reserved for scheduled tasks
-
-  shared/                 (created by the build)
-    server.ts             GENERATED typed client: the Server proxy + @data codecs
-```
-
-The **`minimal`** template is the same layout with far fewer files: `client/` has just `layout.tsx`, `routes/index.tsx`, and `styles/main.css`; `server/` has `main.ts` and `core/AppHandler.ts` with a single example endpoint.
-
-A few files are worth calling out now, and the next page ([Project structure](./project-structure.md)) walks through all of them:
-
-- **`shared/server.ts` does not exist yet** in a fresh project. It is generated the first time you run `toiljs dev` or `toiljs build`. That is normal and expected.
-- **`toil-routes.d.ts`** starts as a stub and gets filled in with your real route names on the first build, which is what makes `Toil.Link` route names type-check.
-- **`.env` and `.env.secrets` are not created** for you. You add them yourself when you need local environment variables or secrets. They are already listed in `.gitignore` so you never commit them. See [Environment and secrets](../services/environment.md).
-
-## Run it
-
-Once scaffolding (and install) finishes, the CLI prints your next steps:
-
-```sh
-cd my-app
-npm run dev
-```
-
-`npm run dev` runs `toiljs dev`, which builds your server to wasm, generates `shared/server.ts`, and starts the dev server with hot reload. Open the printed URL (by default `http://localhost:3000`) and you have a live app.
-
-If you told the wizard **not** to install dependencies, run `npm install` first.
-
-## Gotchas and notes
-
-- **Scaffolding into a non-empty folder** asks for confirmation in interactive mode, and fails in `--yes` mode. Create into a fresh, empty directory.
-- **The project name must be a valid package name** and must stay inside the current directory (no `..`, no absolute paths).
-- **Git init is best-effort.** If `git` is not installed, the CLI skips that step and keeps going.
-- **You do not run `toilscript` yourself.** It is added as a dependency and driven by `toiljs dev` / `toiljs build`.
-
-## Related
-
-- [Project structure](./project-structure.md)
-- [Your first app](./first-app.md)
-- [The CLI reference](../cli/README.md)
-- [Configuration](../concepts/config.md)
-- [Styling](../frontend/styling.md)

package/docs/getting-started/deploy.md

@@ -1,101 +0,0 @@
-# Deploying a toiljs app
-
-This page is an honest look at how you get a toiljs app in front of real users. There are two paths, and it helps to be clear about which one exists today.
-
-- **Self-host it yourself.** You build the app and run it on a machine you control, with `toiljs build` then `toiljs start`. This works right now, on your laptop, a VPS, or any server that can run Node.js.
-- **Run it on the managed Dacely edge.** This is the platform toiljs is built for: a worldwide fleet of servers that runs your compiled backend close to every user. It is the target the whole framework is designed around.
-
-One thing up front, so you do not go looking for it: **there is no `toiljs deploy` command.** The CLI can build and self-host; pushing a build onto the managed edge is a platform step, not a CLI subcommand. The rest of this page covers what you can do today (self-hosting) and what the managed edge gives you.
-
-## The one build powers both
-
-Both paths serve the exact same artifacts. `toiljs build` produces them once:
-
-```mermaid
-flowchart LR
-    A["Your project"] -->|toiljs build| B["build/client/<br/>(HTML, JS, CSS, assets)"]
-    A -->|toiljs build| C["build/server/release.wasm<br/>(your backend)"]
-    B --> H["toiljs start<br/>(self-host)"]
-    C --> H
-    B --> E["managed Dacely edge<br/>(worldwide)"]
-    C --> E
-```
-
-So you never build differently for the two targets. You build once, then either run it yourself or hand the same output to the edge.
-
-## Self-hosting with `toiljs start`
-
-`toiljs start` runs your built app on a fast production HTTP server. It serves your static client, dispatches dynamic requests into your `release.wasm`, does server-side rendering, runs daemons, and exposes a `/_toil` websocket channel. Use it to put your app on your own machine or server instead of the managed edge.
-
-### Step 1: build
-
-`start` serves whatever is in `build/`, so you must build first. If there is no build, `start` exits with an error (it looks for `build/client/index.html`).
-
-```bash
-npm run build
-```
-
-### Step 2: start
-
-```bash
-# Serve on http://127.0.0.1:3000 (loopback only, one worker per CPU).
-npx toiljs start
-
-# Accept outside connections, on port 8080, with 4 worker processes.
-npx toiljs start --host 0.0.0.0 --port 8080 --threads 4
-```
-
-### start flags
-
-| Flag | Meaning |
-| --- | --- |
-| `--port <n>` | Port to listen on. Default `3000` (or `client.port` from your config). |
-| `--host <host>` | Address to bind. Default `127.0.0.1`, which is **loopback only** (reachable just from the same machine). Pass `0.0.0.0` to accept connections from other machines. |
-| `--threads <n>` | Number of HTTP worker processes. Default is automatic (one per available CPU). Pass `1` to disable the worker pool. `--workers` is an accepted alias, and you can also set `server.threads` in your config or the `TOILJS_THREADS` environment variable. |
-| `--root <dir>` | Run against a project in another directory instead of the current one. |
-
-These flags are verified against the CLI. Note that `--host` and `--threads` are `start`-only: `toiljs dev` always binds locally and does not take them. For the full command reference, see [the CLI](../cli/README.md#toiljs-start).
-
-### A realistic self-host
-
-On a small server (say a VPS), a minimal run looks like this:
-
-```bash
-# Install and build.
-npm ci
-npm run build
-
-# Bind on all interfaces so a reverse proxy or the public can reach it.
-npx toiljs start --host 0.0.0.0 --port 8080 --threads 4
-```
-
-Then put a reverse proxy (nginx, Caddy) in front for TLS and a real hostname, pointing it at `http://127.0.0.1:8080`. Keep the process alive with your usual tool (systemd, pm2, a container restart policy).
-
-### Self-host gotchas
-
-- **`start` needs a fresh build.** It serves `build/`, not your source. After any code change, run `toiljs build` again before restarting.
-- **The default bind is loopback.** With no `--host`, only the same machine can reach it. Set `--host 0.0.0.0` (usually behind a reverse proxy) to serve real traffic.
-- **Self-host is one place, not the whole world.** You get one server (or however many you run yourself). The latency and worldwide reach of the managed edge is exactly the thing self-hosting does not give you.
-- **The database is different.** Self-hosting runs the built server, but ToilDB's worldwide data layer is an edge feature. Treat self-host as a way to run and test your build, not as a substitute for the managed edge's global database.
-
-## The managed Dacely edge
-
-The managed **Dacely edge** is the platform toiljs targets: a fleet of servers in many cities that runs your compiled backend as close to each user as possible, backed by the worldwide **ToilDB** database. You write one project, and the build already decides which part of your code belongs to which layer of the edge.
-
-Your backend runs across four **compute tiers**, from a per-request handler at the very edge up to a single worldwide coordinator:
-
-| Tier | Name | Where it runs | Typical code |
-| --- | --- | --- | --- |
-| **L1** | Hot / edge | The node nearest the user, fresh per request | `@rest`, `@service` / `@remote` |
-| **L2** | Regional | One box per connection, per region | `@stream` (Regional) |
-| **L3** | Continental | One box per connection, per continent | `@stream` (Continental) |
-| **L4** | Global / daemon | Exactly one leader worldwide | `@daemon`, `@scheduled` |
-
-Because the same `toiljs build` output feeds the edge, everything you built and tested with `toiljs dev` and `toiljs start` is what runs there. The edge decides each server's role for you; you do not configure tiers by hand. For the full picture of what each tier means and how to write for it, see [Compute tiers (L1 to L4)](../concepts/tiers.md).
-
-## Related
-
-- [The CLI](../cli/README.md): the full reference for `build` and `start` and every flag.
-- [Configuration (`toil.config.ts`)](../concepts/config.md): `server.threads` and the other self-host knobs.
-- [Compute tiers (L1 to L4)](../concepts/tiers.md): how your code maps onto the managed edge.
-- [Getting started](./README.md): the path from install to a running feature.