npm - @zerotal/arch - Versions diffs - 1.8.1 → 1.10.0 - Mend

@zerotal/arch 1.8.1 → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (64) hide show

package/api-surface.md +6 -6
package/docs/admin/actions.md +15 -0
package/docs/admin/auth.md +10 -0
package/docs/admin/dashboard.md +12 -0
package/docs/admin/extending-ui.md +14 -0
package/docs/admin/forms.md +15 -0
package/docs/admin/operations.md +12 -0
package/docs/admin/resources.md +6 -0
package/docs/admin/tables.md +21 -0
package/docs/audit.md +5 -0
package/docs/authentication.md +110 -1
package/docs/broadcasting/references.md +17 -0
package/docs/cache.md +5 -0
package/docs/carbon.md +5 -0
package/docs/changelog.md +281 -0
package/docs/client/index.md +17 -0
package/docs/commands.md +6 -0
package/docs/components.md +73 -0
package/docs/config-system.md +54 -0
package/docs/cookies.md +6 -0
package/docs/deployment.md +151 -13
package/docs/devtools.md +5 -0
package/docs/email-verification.md +26 -1
package/docs/encryption.md +21 -0
package/docs/errors.md +2 -0
package/docs/flow/components.md +54 -0
package/docs/flow/forms.md +57 -0
package/docs/flow/references.md +14 -0
package/docs/getting-started.md +38 -0
package/docs/health.md +19 -0
package/docs/helpers.md +150 -0
package/docs/i18n.md +5 -0
package/docs/inertia/middleware.md +44 -0
package/docs/inertia/props.md +70 -0
package/docs/inertia/ssr.md +95 -10
package/docs/lock.md +15 -0
package/docs/logger.md +38 -0
package/docs/middleware.md +31 -0
package/docs/migrations.md +47 -0
package/docs/monitor.md +59 -0
package/docs/notifications.md +11 -0
package/docs/orm/casts.md +6 -0
package/docs/orm/lifecycle.md +18 -0
package/docs/orm/queries.md +10 -0
package/docs/orm/relationships.md +30 -0
package/docs/queue.md +10 -0
package/docs/rate-limiting.md +84 -21
package/docs/responses.md +23 -0
package/docs/routing.md +16 -0
package/docs/scheduler.md +82 -8
package/docs/session.md +6 -0
package/docs/social.md +10 -0
package/docs/storage.md +21 -0
package/docs/support-policy.md +13 -1
package/docs/telemetry.md +8 -0
package/docs/tenancy.md +6 -0
package/docs/testing/index.md +105 -0
package/docs/upgrade.md +48 -0
package/docs/validator.md +9 -0
package/docs/view.md +6 -0
package/package.json +3 -3
package/src/install/guidelines.ts +1 -1
package/src/mcp/stdio.ts +3 -3
package/src/tools/_probe.ts +2 -2

package/docs/changelog.md CHANGED Viewed

@@ -27,6 +27,287 @@ the section for every version you cross and apply its migration notes, not only
 majors. [Releases and versioning](/docs/support-policy#releases-and-versioning) explains
 when that carve-out ends.
+## 1.10.0 — 2026-08-30
+A second report from the team building on Zerotal, and the things it found. Most of this
+release is failures that were silent by construction — mail delivered nowhere, a page
+shared as a grey rectangle, a schedule that never fired, a rate limiter with one bucket
+for everybody. None of them logged anything.
+**Three things to know before upgrading.**
+- **React apps using SSR now need `@inertiajs/react` installed.** It is the same adapter
+  your browser entry point already uses; the server renders through its `<App>` so
+  `<Head>` works. A missing one is a named error rather than a silent omission.
+- **`scheduler.timezone` does something now.** It was documented as informational and read
+  by nothing. Its default moved from the literal `"UTC"` to **the system zone**, so an app
+  that never set the key keeps doing exactly what it did — but an app that set it now gets
+  what it asked for. If you set it to `"UTC"` on a server that is not on UTC, your
+  schedules will move. See [the upgrade guide](/docs/upgrade#1-9-to-1-10).
+- **Named rate limiters need `.trustedProxies(n)` behind a proxy.** `.byIp()`, `.byUser()`
+  and `.byApiKey()` now ignore `X-Forwarded-For` unless told how many proxies sit in
+  front, which is the same rule `ThrottleMiddleware` already followed. `zt doctor` reports
+  any that need it.
+### Added
+- **`zt assets:prune`** — removes the chunks an earlier release left behind, on the machine
+  that never ran a build. `assets:build --clean` cleans the directory it _builds into_,
+  which does nothing for the usual release shape: build here, tar the output, extract it
+  over `public/` there. Extracting merges, so every deploy adds another set of
+  content-hashed chunks and none are ever removed. One app reached 225 chunk files for the
+  49 its entry point references. Ship `.zerotal/` with the release and this removes what
+  the build record does not claim. See [Deployment](/docs/deployment#assetsprune--clearing-up-after-the-extract-instead-of-before-it).
+- **`zt deploy:<env> --check`** — the preflight gate on its own, for the point in a release
+  script where the new code is on disk and the service has not restarted. Exit 0 and
+  restart; exit non-zero and keep serving the previous release. Everything that can refuse
+  already runs by the end of preflight and none of it mutates, so stopping there is a
+  complete answer rather than half a deploy.
+- **`RateLimiter.trustedProxies(n)`** on the fluent builder, and
+  **`res.assertInertiaRedirect(url)`** in `@zerotal/testing` — the assertion that checks
+  what actually breaks on an Inertia redirect, which is the `X-Inertia` marker rather than
+  the status and `Location` a normal redirect assertion already covers.
+- **`@zerotal/core/runtime`** (`zerotal/runtime`) — the runtime checks as exports, so a
+  script or a test can make the same assertion `zt` makes: `runtimeBelowFloor`,
+  `declaredBunFloor`, `runtimeMismatch`, `bunBinary` and the messages that go with them.
+- **`definedOnly()` and `Resolved<T>`** on `@zerotal/core/helpers`, for merging an options
+  bag over defaults without an explicit `undefined` overwriting one.
+- **Scheduler timezone helpers** — `wallClockIn`, `isValidTimeZone`,
+  `CronExpression.matchesIn` and `CronExpression.nextRunAfterIn`, plus `SchedulerError` and
+  `UnknownTimeZoneError`.
+- **A boot line when a convention is skipped in this environment.** An env-restricted
+  concern is skipped by _not looking_, which is correct and completely silent: an app ran
+  for weeks in production with `app/schedules` full and no worker process, and nothing
+  logged anything because from a web process's point of view nothing existed.
+### Changed
+- **Optional properties in public option shapes are declared `?: T | undefined`.** The
+  generated `tsconfig.json` enables `exactOptionalPropertyTypes`, under which
+  `image?: string` refuses a key that is present and holds `undefined` — so
+  `{ image: candidate ?? undefined }`, the most ordinary thing there is, did not compile
+  and every conditionally-absent field had to be spelled `...(x ? { x } : {})`. 438
+  properties across 115 files. Nothing changes for a reader: an absent optional property
+  already read as `undefined`.
+- **`scheduler.timezone` is honoured**, and its default is the system zone rather than the
+  literal `"UTC"`. See the note above.
+- **`mail.driver: "log"` fails `zt doctor` in production** when `mail.from.address` has been
+  configured, and warns when it is still the placeholder. Mail written to a log file is
+  delivered to nobody and says so nowhere.
+### Fixed
+- **React SSR emitted no `<Head>` tags at all.** The React branch rendered the page
+  component directly, and `<Head>` renders nothing — it reports its children to a head
+  manager it reads from context, and rendering the component alone puts none there. So
+  every page served the template's `<head>`: no title, no description, no card. Nothing
+  failed and nothing logged, because the page is perfect in a browser, where React has run.
+  Only the readers that do not run JavaScript saw it — which is every link-preview scraper
+  and every `curl`.
+- **SMTP submission on port 587 sent nothing.** The STARTTLS handshake completed and then
+  the client's `EHLO` was dropped: `upgradeTLS()` returns the new socket while the
+  handshake is still in flight, and a write issued in that window is lost — not buffered,
+  not an error, gone. Port 465 was unaffected, so mail worked on the port nobody documents
+  and the 587 every provider _does_ document produced silence: no error, no bounce, no log
+  line, and password resets that never arrived.
+- **TLS certificates were not actually verified, on either SMTP transport.**
+  `rejectUnauthorized` is not enforced by the runtime — it reports a self-signed
+  certificate as authorized and puts the real reason beside it — so the connection was
+  encrypted and would have accepted that encryption from anyone in the network path. The
+  driver reads the handshake result itself now and fails closed.
+- **A scheduled task with a `timezone` took the whole scheduler down.** `Bun.cron`'s options
+  form throws, and it throws during registration, so the worker died on boot and
+  restart-looped: one task with a timezone stopped every task in the app. Zerotal evaluates
+  the zone itself now, and a task that cannot register takes only itself out.
+- **Named rate limiters ignored `trustedProxies`, and `zt doctor` was told not to look.**
+  `.byIp()`, `.byUser()` and `.byApiKey()` used a resolver that read the socket address and
+  fell back to the leftmost `X-Forwarded-For` entry with no proxy count. Behind a reverse
+  proxy every visitor keyed on the proxy's own address and shared one bucket, so a `login`
+  limiter of five attempts a minute was five attempts a minute for the entire user base and
+  one attacker locked everybody out. The doctor check written to catch this exempted any
+  custom `keyResolver`, which is what all three are.
+- **`ctx.session.intended()` could not read what `AuthMiddleware` stored.** It used the key
+  `intended` while the middleware and `redirect().intended()` used `intended_url`. Each pair
+  was internally consistent and separately tested, so every test passed — and an app that
+  mixed them, which the documentation invited, was silently sent to `/` after every sign-in.
+- **`MonitorStore` overwrote its own defaults with `undefined`.** It applied `?? …` defaults
+  and then spread `...opts` after them, and spread copies own properties even when they
+  hold `undefined` — so an unset config put `undefined` back over the retention window and
+  `prune()` computed a `NaN` cutoff, pruning nothing and reporting nothing.
+- **`engines.bun` is enforced.** Every generated app writes a floor and nothing read it.
+  `Intl` output moves between Bun releases, so a suite with currency or date assertions goes
+  red on a runtime that is otherwise fine and the failures name the code they touch rather
+  than the binary.
+- **The asset build record is portable.** Its filename was hashed from the output
+  directory's _absolute_ path, so a record shipped with a release matched nothing at the
+  other end and moving a checkout silently orphaned it.
+- **The React SSR root is marked `data-server-rendered`**, so the client hydrates the markup
+  instead of discarding it and rendering the page a second time. `POST /__ssr` returns the
+  same body shape as the Vue branch.
+### Documented
+- **["What a crawler sees"](/docs/inertia/ssr#what-a-crawler-sees)** — `inertia()` does not
+  server-render the component, which is the normal Inertia arrangement and worth saying out
+  loud: the served document is a `<title>` and a JSON blob. Which readers run JavaScript,
+  which do not, and the three ways to give the second group something to read.
+- **[Which Inertia redirects are covered](/docs/inertia/middleware#which-redirects-are-covered)**
+  — all of them, because `useOnce()` registers the middleware globally. Written down because
+  the opposite belief is what keeps an app's own workaround on every request forever.
+- **[`bun test` vs `bun zt test`](/docs/testing#bun-test-vs-bun-zt-test)** — the 30-second
+  timeout (the `bunfig.toml` key is ignored by Bun and `setDefaultTimeout()` in a preload
+  reaches only the first file, so the flag is the only mechanism that works), the runtime
+  check, and the fact that configuration resolves once per process — so a test that mutates
+  the environment in `beforeAll` is testing whichever file booted first.
+- **[Timezones](/docs/scheduler#timezones)** in the scheduler, **[the middleware names the
+  framework occupies](/docs/middleware#names-the-framework-already-occupies)**, and why
+  `X-Forwarded-For` is [counted from the right](/docs/rate-limiting#trustedproxies).
+## 1.9.0 — 2026-08-29
+The gaps an app was filling in for itself: one Bun per project, a database backup that is not
+`cp`, a release gate the pipeline will actually call, a boundary between a model and a page
+prop, and helpers that work on both sides of the wire.
+**Two things to know before upgrading.** Both are new refusals or new noise, and both are quiet
+if they do not apply to you.
+- **`zt` now refuses to run when a project has two Bun runtimes in it** — the shell's `bun` and
+  a different one in `node_modules`. If it fires, pick one: `bun update bun` moves the installed
+  copy to match your shell, or run everything through `node_modules/.bin/bun`. To boot anyway
+  while you sort it out, set `ZT_ALLOW_RUNTIME_MISMATCH=1`. Most projects never see this,
+  because most have no `bun` in `node_modules` to disagree with.
+- **Passing an ORM model straight into an Inertia page prop now warns in development**, once per
+  model class, if that model declares neither `hidden` nor `visible`. Declaring either silences
+  it — and is the fix, not the silencer. Production is unaffected.
+### Added
+- **One project, one Bun.** `engines.bun` is a floor and nothing enforced it, so an app could be
+  served by one runtime and tested on another — the shell's `bun` and a `node_modules/bun` put
+  there by a transitive peer dependency nobody declared. A green suite is then evidence about a
+  binary the app is not served by. `startZerotal()` refuses on a mismatch, and `zt test` spawns
+  the binary running it rather than a name `PATH` resolves.
+- **`zt db:backup`** — a verified snapshot of the SQLite database, using `VACUUM INTO` rather
+  than `cp`. Copying a live SQLite file can capture a half-written page and produce a backup
+  that restores as a corrupt database, months later, from the one file you were relying on.
+  Every snapshot is opened and integrity-checked as it is written, `--require-rows` fails a
+  backup whose business tables are empty, `--rehearse` performs the actual restore, and every
+  failure path exits non-zero — a backup timer that reports success while writing nothing is
+  worse than no timer at all. See [Deployment](/docs/deployment#back-up-the-database).
+- **`DeployTarget.preflight`** — a slot for the app's own release gate, run after the config
+  validators and `doctor` and before anything is built or migrated. A command named
+  `release:check` is found by convention, with nothing to wire up. A declared name that is not
+  registered **fails** the deploy rather than being skipped: a gate nothing calls is a comment.
+- **`zerotal/shared`** — the helpers with no server in them, importable from a browser bundle:
+  `pluralize`, `Str`, and new `formatMoney` / `formatNumber` / `formatDate`. A total that reads
+  `R 39 147` on screen and `R39,147.00` on the invoice looks like two different numbers to the
+  person paying it, and maintaining that in two files is how it happens. See
+  [Helpers](/docs/helpers#sharing-helpers-with-the-browser--zerotalshared).
+- **`<form data-enhance>`** — a plain server-rendered page, with no Flow component on it, can
+  submit without the page flashing. It posts through `fetch` and the matching form in the
+  response replaces it in place, so a validation error lands where the person is looking. Its
+  own dependency-free bundle at `/__flow/enhance.js`, added with `flowEnhanceTag()` in the
+  layout. Every path degrades: a network failure re-submits natively, a redirect is followed and
+  `pushState`d, and no JavaScript at all is an ordinary form post.
+- **Three new `doctor` checks.** A rate limiter that cannot tell two people apart behind a proxy
+  — where the socket address is the proxy's for every request, so one attacker can lock out
+  everybody. Auth columns missing from a table a migration built without them, which otherwise
+  surfaces as `no such column` in tests that have nothing to do with email. And migrations that
+  have not run, named, before a request finds out.
+### Changed
+- **A model reaching Inertia page props says what it is safe to publish.** Page props are page
+  source, and `return inertia("Trips/Show", { trip })` ships every column of the row — the
+  internal cost, the margin, the note about the customer, on the customer's own screen. The
+  ORM's `hidden` / `visible` lists were already honoured and nothing said so. See the upgrade
+  note above and [Inertia props](/docs/inertia/props#page-props-are-page-source).
+- **A bound field the model will not accept says so.** `flow:model` on a column missing from
+  `fillable` was dropped in silence: the form submitted, nothing was written, nothing failed.
+  The drop stays — the same path receives whatever a browser sends — but a developer's typo no
+  longer produces the same silence as a hostile payload. Development only, once per field.
+- **INTERNAL: 116 exports leave the recorded API surface** across `core`, `orm`, `flow`,
+  `admin`, `flow-ui` and `monitor`. **Nothing is removed and nothing breaks** — they are still
+  exported and still work; what changes is the promise. The dev orchestrator, the ORM's
+  connection wiring and dialect layer, the admin panel's page machinery and Flow's
+  wire-protocol frame types are not things an app constructs, and naming them in a `stable`
+  surface implied a guarantee about a protocol that is free to change. Each package's own
+  changelog lists its share.
+- **A minor breaks nothing that can wait.** The roadmap used to say a minor never breaks
+  anything, which was false when written — three breaks had already shipped in minors, each
+  deliberately, each with a note, exactly as the [support policy](/docs/support-policy) has
+  always described. An absolute rule the project knowingly broke is worse than an honest one.
+### Documented
+- **Every promised export is documented — 100%, up from 60%.** `maturity: stable` means an
+  export keeps its shape for the rest of the 1.x line, and the gate measuring how much of that
+  promise was written down stood at 798 gaps. It is zero.
+  Four features turned out to have shipped and been invisible. **Passkeys** — `PasskeyService`
+  has been here since 1.7.0 with no page at all, including that `requireUserVerification`
+  defaults to `true` because that is what makes a passkey a second factor rather than one.
+  **`@zerotal/core/env`**, a typed environment schema that reports every bad variable at once
+  rather than one per restart. **The outbound `Http` client**, which the testing guide had been
+  linking to a page that did not describe it. And **`@zerotal/monitor`'s Export JSON**, where the
+  button was documented and the forty-odd row types it hands you were not.
+  Also named for the first time: `@zerotal/flow-ui`'s sixty-one component prop types, which a
+  wrapper component cannot be written without.
+  The gate itself could not see `.tsx` files: with `jsx` unset, TypeScript declines to pull such
+  a module into the program rather than failing to parse it, so every symbol in one was
+  invisible. It had been inflating exactly the TSX-heavy packages.
+### Fixed
+- **A rebuilt Inertia bundle no longer 404s on a chunk the browser asks for.**
+  `resources/js/app.tsx` builds to `/assets/app.js` under that name every time, while
+  `splitting: true` names each chunk after its content. A rebuild therefore rewrites `app.js` to
+  import `chunk-NEW.js` and prunes `chunk-OLD.js` — and a browser holding a cached `app.js` asks
+  for the pruned one:
+      GET /assets/chunk-hrnspqda.js  status=404
+  from a page that renders and a server that is healthy, with nothing in that line leading back
+  to the template.
+  The template hardcodes `/assets/app.js` rather than calling `asset()`, so the version token the
+  rest of the framework appends never reached it — and cache-busting had only ever been
+  implemented for `serve --dev`. It now applies in every environment: the file's mtime in dev,
+  where a rebuild happens without a restart, and the boot-derived asset version otherwise. An
+  unchanged asset keeps a stable URL and stays cached, which is why the token is derived rather
+  than random.
 ## 1.8.1 — 2026-08-26
 DevTools showed you the wrong request, accurately.

package/docs/client/index.md CHANGED Viewed

@@ -328,6 +328,23 @@ This package also ships `Socket`, `Channel` and `PresenceChannel` — a WebSocke
 client speaking Zerotal's broadcast protocol. Different job, documented where it is
 used: [Broadcasting → Client](/docs/broadcasting/client).
+## Types
+The typed client derives its shape from your app's routes, so most of these are inferred rather
+than written by hand — but a helper that wraps a call needs to name them:
+| Type                                         | What it is                                                                                                               |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `ApiRouteMap`                                | The generated route table the client is typed against.                                                                   |
+| `RouteShape`                                 | One route's method, params, body and response.                                                                           |
+| `PathsFor<M>`                                | Every path answering a given method — what makes an unknown path a compile error.                                        |
+| `PathParams`, `ParamRecord`                  | The params a path captures.                                                                                              |
+| `BodyOf<P>`, `QueryOf<P>`, `ResponseOf<P>`   | One route's request body, query and response types.                                                                      |
+| `ResponseMeta`                               | Status, headers and timing carried alongside a response.                                                                 |
+| `RequestInterceptor`, `ResponseInterceptor`  | Hooks running before a request leaves and after one returns — auth headers, retry, logging.                              |
+| `CircuitBreakerOptions`                      | When the client stops calling an endpoint that keeps failing, and when it tries again.                                   |
+| `SocketOptions`, `SocketState`, `SocketLike` | The realtime socket: how it connects, where it is in its lifecycle, and the minimum interface a substitute must satisfy. |
 ## Next steps
 - [Rate Limiting](/docs/rate-limiting) — throttle what you send and what you accept.

package/docs/commands.md CHANGED Viewed

@@ -370,10 +370,16 @@ can gate a deploy.
 | `bun zt migrate:status`       | Show the status (run / pending / batch) of each migration file |
 | `bun zt migrate:generate`     | Auto-generate a migration from model schema changes            |
 | `bun zt db:seed`              | Run all seeders from `database/seeders/`                       |
+| `bun zt db:backup`            | Take a verified SQLite snapshot with `VACUUM INTO`             |
 > **Danger** — `migrate --fresh` and `migrate:fresh` drop every table before
 > re-running migrations. Never run them against a production database.
+`db:backup` is the counterpart to everything above it: those commands all assume the database
+file will still be there. It verifies every snapshot it writes and exits non-zero on any
+failure, so it is safe to run from a timer — see
+[Deployment](/docs/deployment#back-up-the-database) for the flags and a systemd unit.
 ### Generators
 | Command                                              | Creates                                                                    |

package/docs/components.md CHANGED Viewed

@@ -2348,6 +2348,79 @@ Or import directly from the package: `import { Prose } from "@zerotal/flow-ui";`
 <!-- END GENERATED COMPONENTS -->
+## Types
+Every component exports the type of its own props, named after it — `Button` takes
+`ButtonProps`, `Dialog` takes `DialogProps`. Reach for them when you wrap a component rather
+than use it directly, which is the usual reason an app needs one:
+```tsx fragment
+import { Button, type ButtonProps } from "@zerotal/flow-ui";
+/** Our save button: the same API, one decision already made. */
+export function SaveButton(props: Omit<ButtonProps, "variant">) {
+  return <Button variant="primary" {...props} />;
+}
+```
+The full set:
+```text
+AccordionProps       AlertDialogProps     AlertProps           AlertTextProps
+AspectRatioProps     AvatarProps          BadgeProps           BreadcrumbProps
+ButtonGroupProps     ButtonProps          CalendarProps        CardElementProps
+CarouselProps        ChartProps           CheckboxProps        CollapsibleProps
+ComboboxProps        CommandProps         ContextMenuProps     DatePickerProps
+DialogProps          DropdownMenuItemProps                     DropdownMenuLabelProps
+DropdownMenuProps    DropdownMenuSeparatorProps                DropdownMenuShortcutProps
+EmptyProps           FieldProps           GvaProps             HoverCardProps
+InputGroupProps      InputOTPProps        InputProps           ItemProps
+KbdProps             LabelProps           MenubarProps         NavigationMenuProps
+PaginationProps      PopoverProps         ProgressProps        ProseProps
+RadioGroupProps      ResizableProps       ScrollAreaProps      SelectProps
+SeparatorProps       SheetProps           SidebarProps         SkeletonProps
+SliderProps          SpinnerProps         SwitchProps          TableProps
+TabsProps            TextProps            TextareaProps        ToasterProps
+ToggleGroupProps     ToggleProps          TooltipProps
+```
+### Values a prop takes
+Several props are unions rather than free strings, and the union is exported so a variable
+holding one can be typed:
+| Type                  | Used by                                                     |
+| --------------------- | ----------------------------------------------------------- |
+| `SelectOption`        | `Select`, `Combobox` — one `{ label, value }` entry.        |
+| `RadioOption`         | `RadioGroup`.                                               |
+| `TabItem`             | `Tabs`.                                                     |
+| `SidebarItem`         | `Sidebar`.                                                  |
+| `TableGroup`          | `Table` — a grouped set of rows.                            |
+| `NavigationPanelLink` | `NavigationMenu`.                                           |
+| `PopoverSide`         | `Popover`, `Tooltip`, `HoverCard` — which side it opens on. |
+| `PopoverAlign`        | The same, for alignment.                                    |
+| `ToastPosition`       | `Toaster` — where toasts stack.                             |
+| `ChartType`           | `Chart`.                                                    |
+| `ClassValue`          | Anything the `class` prop accepts, before merging.          |
+### Sub-components
+A few components are used as a small set rather than one tag: `AlertTitle` and
+`AlertDescription` inside `Alert`, `DropdownMenuShortcut` inside a menu item. The prose
+components — `Blockquote`, `Lead`, `H2`, `H3`, `H4` — are the same idea for `Prose`.
+### Variants and theming
+Each variant-bearing component exports its own `cva` config, so a wrapper can reuse the exact
+class set rather than re-deriving it: `buttonVariants`, `badgeVariants`, `alertVariants`,
+`spinnerVariants`, `toggleVariants`, and `popoverSurface` for the floating surfaces.
+`GvaConfig` is the shape they are built from.
+Theming is `flowTokensCss` (the CSS custom properties), `flowTailwindConfig` (the Tailwind
+preset that reads them), and `FlowUiThemeConfig` for `config/flow-ui.ts`. `THEME`,
+`THEME_STORAGE_KEY` and `THEME_TOGGLE_SCRIPT` are the light/dark toggle: the script runs before
+first paint, so a page does not flash the wrong theme on load.
 ## Testing
 Set your suite up once as described in [Testing](/docs/testing). A `flow-ui`

package/docs/config-system.md CHANGED Viewed

@@ -42,6 +42,45 @@ const apiKey = env("API_KEY"); // no fallback → string | undefined
 > **Note** — When you need a value to be present, use `requireEnv("APP_KEY")` instead — it throws a `ConfigError` at boot if the variable is unset, rather than returning `undefined`.
+### Declaring the whole environment — `EnvSchema`
+`env()` is per-call and forgiving: an unset variable is `undefined` and you find out where it is
+used. `@zerotal/core/env` is the other end — declare every variable the app reads, once, and the
+boot either produces a fully typed frozen object or fails with every problem listed at the same
+time:
+```typescript fragment
+// env.ts
+import { EnvSchema, t } from "@zerotal/core/env";
+export const env = EnvSchema.define({
+  APP_KEY: t.string().min(32),
+  PORT: t.port().default(3000),
+  DATABASE_URL: t.string(),
+  LOG_LEVEL: t.enum(["debug", "info", "warn", "error"]).default("info"),
+  SENTRY_DSN: t.url().optional(),
+});
+env.PORT; // number — never undefined, because it has a default
+env.LOG_LEVEL; // "debug" | "info" | "warn" | "error", narrowed to the literals
+```
+**It reports every failure at once.** A schema with three missing variables fails the boot
+naming all three, rather than one per restart — which is the difference between one fix and
+three round trips through a deploy. The failure is an `EnvSchemaError` carrying an
+`EnvFieldError` per field.
+| Type             | What it is                                                                  |
+| ---------------- | --------------------------------------------------------------------------- |
+| `EnvSchemaError` | The boot failure, listing every field that did not validate.                |
+| `EnvFieldError`  | One field's problem: which variable, and what was wrong with it.            |
+| `FieldType`      | The builders `t` offers — string, number, boolean, port, url, enum.         |
+| `EnvOutput<S>`   | The typed object a schema produces. `typeof env` where you need to pass it. |
+| `InferDef<D>`    | The type one field definition resolves to.                                  |
+Use `env()` for a value read in one place and `EnvSchema` for the set an app cannot start
+without. They coexist; the schema is not a replacement for the helper.
 ## Config files
 Config files live in `config/`. Each file exports a typed object via a package helper:
@@ -250,6 +289,21 @@ if (config("app.env") === "production") {
 | `ConfigLoader.get`      | `get(key: string, fallback?): value`                       | Dot-path read against the loaded map.                                                     |
 | `ConfigLoader.validate` | `validate(): this`                                         | Run each file's optional `validate(config)` export, throwing on failure.                  |
+## Types
+| Type                | What it is                                                                             |
+| ------------------- | -------------------------------------------------------------------------------------- |
+| `ConfigValidator`   | What `registerConfigValidator` takes — a function handed the config, reporting issues. |
+| `ConfigIssue`       | One finding: its namespace, message, and level.                                        |
+| `ConfigIssueLevel`  | Whether an issue refuses a production boot or is only worth reading.                   |
+| `ConventionsConfig` | The `conventions` namespace — where the framework looks for models, jobs and the rest. |
+| `AppTlsConfig`      | TLS settings under `app.tls`.                                                          |
+| `AssetLoaderKind`   | How an asset is loaded by the build — the `loader` values `assets.loaders` accepts.    |
+A validator reporting a **fatal** issue refuses a production-like boot rather than warning. That
+is the whole point of the level: an app that boots with a broken configuration serves wrong
+answers rather than failing, and the failure is the cheaper outcome.
 ## Next steps
 - [Conventions](/docs/conventions) — the auto-discovery settings under the `conventions` key.

package/docs/cookies.md CHANGED Viewed

@@ -93,6 +93,12 @@ You rarely set cookies by hand — two parts of the framework manage their own:
   (non-`HttpOnly`) cookie after every request so Axios/Inertia can echo it back as
   the `X-XSRF-TOKEN` header.
+## Types
+`CookieOptions` is what every cookie-setting call accepts — `maxAge`, `path`, `domain`,
+`httpOnly`, `secure`, `sameSite`. It is exported so a helper that sets a cookie in more than one
+place can take the same shape.
 ## Next steps
 - [Session](/docs/session) — signed, `HttpOnly` cookie-backed state (the usual choice).