@voltro/cli 0.27.0 → 0.29.0

package/templates/agent-docs/routing.md

@@ -785,6 +785,38 @@ export default function NotePage(): ReactNode {
 
 `useLoaderData<T>()` returns the loader's resolved value, typed via the generic.
 
+**On a page that declares a `loader`, the value is always there.** The router
+never renders such a page without its data: a settled loader commits its data
+and the displayed route together, a pending one shows the `Pending` skeleton
+(or keeps the previous page), and one that threw renders the error subtree. You
+do not need a guard, and adding one only hides a real mistake behind a `?.`.
+
+**Calling it where no `loader` exists is an error, and it says so.** A level with
+no `loader` export throws:
+
+```text
+useLoaderData() was called at a level that declares no `loader`. Export `loader`
+from this page/layout, or — if this component is shared between routes that have
+one and routes that do not — read it with `useOptionalLoaderData()` …
+```
+
+Note what is NOT an absence: an empty **result**. A loader returning
+`{ items: [] }` returns exactly that. `undefined` never means "the query found
+nothing" — it means "there is no loader at this level".
+
+### `useOptionalLoaderData()` — for a component on both kinds of route
+
+One case needs it: a component genuinely mounted both under routes that declare
+a loader and routes that do not. It returns `undefined` instead of throwing.
+
+```tsx
+const data = useOptionalLoaderData<Data>()
+const project = data?.project
+```
+
+A loader that legitimately resolves to `undefined` is not an error — both hooks
+hand that `undefined` back. Only the missing `loader` throws.
+
 ## When loaders run
 
 | renderMode | When loader runs |
@@ -830,6 +862,23 @@ export default function Profile() {
 
 Because the SSR markup and the hydration render read the same loader value, they match — no hydration flicker — and you don't hand-build a seed store to bridge the two. This is distinct from `fallback`, whose value never came from the server and so keeps `loading: true`; use exactly one of the two.
 
+> **Seed whatever the screen checks FIRST, not whatever is most interesting.**
+> A component's server render stops at its OUTERMOST unsatisfied gate, so an
+> unseeded subscription in an early branch hides every seeded one below it:
+>
+> ```tsx
+> // Seeding `roadmap` changes nothing while this branch is the first one.
+> if (availableYearsIdle || availableYearsLoading) return <Spinner />
+> return <Roadmap data={roadmap} />
+> ```
+>
+> The symptom is a page that still server-renders a spinner after you seeded
+> the data you care about. Walk the component's early returns from the top and
+> seed each subscription they read, or move the gate below the render you want.
+> The same applies to an auth gate: a `useSubscription`-backed
+> `AuthenticationProvider` has no data during a server render, so every page
+> under it renders its loading state until that subscription is seeded too.
+
 Client-side navigation is unchanged: moving to another route runs that route's
 loaders in the browser as usual. A `spa` page has no server render, so its
 loader runs on the client on first mount.
@@ -1152,14 +1201,22 @@ The third context field — `locale: string` — is the active i18n locale for t
 
 ```tsx
 import { getCatalog } from '../lib/locale'
-import { localeCanonicalUrl } from '../lib/seo'
+import { seoAlternates } from '@voltro/web'
 
 export const meta = ({ locale }: { locale: string }): PageMeta => {
   const c = getCatalog(locale)
   return {
     title:       c['seo.notes.title']       as string,
     description: c['seo.notes.description'] as string,
-    canonical:   localeCanonicalUrl('/notes', locale),
+    // Canonical URL for THIS locale + a reciprocal `hreflang` alternate for
+    // every locale (incl. `x-default`), spread straight into the meta.
+    ...seoAlternates({
+      siteUrl:       'https://notes.example.com',
+      path:          '/notes',
+      locale,
+      locales:       ['en', 'de'],
+      defaultLocale: 'en',
+    }),
   }
 }
 ```
@@ -1168,6 +1225,40 @@ export const meta = ({ locale }: { locale: string }): PageMeta => {
 
 `loaderData` is the PAGE loader's result. Because `meta` runs server-side after the loader, the SSR'd `<head>` is already correct on first paint — no client-side title patching, no flash.
 
+## Technical SEO: canonical, hreflang, sitemap & robots
+
+The framework ships the cheap technical-SEO primitives so an indexable app gets them without app-level plumbing.
+
+**Canonical + hreflang helpers** (`@voltro/web`) are pure functions you call from `meta`. They are browser-safe, so importing them into a `*.page.tsx` never drags a server module into the client bundle:
+
+- `canonicalUrl(siteUrl, path)` — one absolute canonical URL.
+- `seoAlternates({ siteUrl, path, locale, locales, defaultLocale })` — returns `{ canonical, links }` where `canonical` is this locale's URL and `links` is one `rel="alternate"` per locale (each an **absolute** URL, as Google requires) plus `hreflang="x-default"`. The alternate set is reciprocal across every locale — exactly what Google's [hreflang rules](https://developers.google.com/search/docs/specialty/international/localized-versions) want. The locale model is URL-PREFIX routing: the default locale on the bare path (`/notes`), other locales prefixed (`/de/notes`).
+
+**Keeping a page out of the index** — set `noIndex` on its meta. It emits `<meta name="robots" content="noindex, nofollow">` AND excludes the route from the generated `sitemap.xml`:
+
+```tsx
+export const meta: PageMeta = { title: 'Checkout', noIndex: true }
+```
+
+**`sitemap.xml` + `robots.txt`** are generated at `voltro build` from the prerendered routes. Turn them on with a `seo.siteUrl` in `app.config.ts`:
+
+```ts
+export default {
+  type: 'web' as const,
+  name:  'Notes',
+  locales: ['en', 'de'],
+  defaultLocale: 'en',
+  seo: {
+    siteUrl:  'https://notes.example.com',
+    disallow: ['/admin'],           // extra robots Disallow prefixes (optional)
+  },
+}
+```
+
+- **`sitemap.xml`** lists every prerendered route (minus `noIndex` ones). With 2+ `locales`, each URL carries the full `xhtml:link` alternate set. Written only when `seo.siteUrl` is set — absolute URLs are required.
+- **`robots.txt`** is generated even without `siteUrl`. Production allows all and advertises the sitemap; `voltro dev` — and any build with `VOLTRO_SEO_NOINDEX=1` (staging / preview deploys) — disallows everything, so a non-production surface never gets indexed by default.
+- A user-authored `public/sitemap.xml` / `public/robots.txt` always wins — the generator never overwrites one.
+
 ## Examples
 
 ### Authenticated dashboard with cookie-driven loader

package/templates/agent-docs/schema-driven-ui.md

@@ -202,6 +202,18 @@ A combined create-or-edit screen is a three-line wrapper:
   `{ fields, values, errors, isValid, pending, setValue, submit, reset }` for
   100% custom JSX — the binding stays.
 
+### Accessible by default
+
+The built-in widgets render accessible HTML without any extra work: a `<label htmlFor>` tied to the control, `aria-required` on required fields (the visual `*` is `aria-hidden` — assistive tech learns "required" from the control, not from a spoken "star"), and, on error, `aria-invalid` + a `role="alert"` message associated via `aria-describedby`. A radio group ties its error to the whole `<fieldset>`.
+
+Add **help text** by putting a `description` on the field's Schema — it renders as a hint and is associated to the control via `aria-describedby`, so a screen reader announces it with the label:
+
+```ts
+Schema.Struct({
+  handle: Schema.String.annotations({ description: 'Shown on your public profile' }),
+})
+```
+
 ## `<DataTable>` — bind to a QUERY
 
 Columns come from the query's output `Schema`; rows are a LIVE subscription

package/templates/agent-docs/templates/apibackends.md

@@ -649,7 +649,7 @@ const execute = async (
   // Post-commit fan-out → the `order.placed` trigger starts the
   // `orders.fulfill` workflow. Guard `ctx.events` so a unit-test ctx
   // without it doesn't throw.
-  await ctx.events?.emit('order.placed', {
+  await ctx.events?.publish(orderPlaced, { orderId: row['id'] as string }, {
     orderId: row['id'] as string, tenantId: input.tenantId,
   })
 

package/templates/agent-docs/testing.md

@@ -372,6 +372,48 @@ What it fills and what it leaves alone:
 
 There is no flag to turn the validation off — a test store that accepts rows production rejects is a fake testing itself. `fixtureRow` is a runtime filler for the loose `store.insert(name, row)` path. For **compile-time** payload typing (a missing required column caught as a type error at the call), use [`insertRow` / `upsertRow`](/docs/data/mutations) from `@voltro/database`, which check against `InferInsertRow<T>`.
 
+## Subscribers — `makeSubscribeContext` + the change constructors
+
+A `*.subscribe.ts` handler does not receive an `AppContext`. It receives a
+change EVENT and a `SubscribeContext`, and both have constructors:
+
+```ts
+import { changeInsert, changeUpdate, changeDelete, changeSoftDelete, makeSubscribeContext, makeTestContext } from '@voltro/testing'
+import subscriber from '../src/attendance.subscribe'
+
+const app = makeTestContext({ store: { attendance: [{ id: 'a1', employeeId: 'e1' }] } })
+const ctx = makeSubscribeContext({ id: 'attendance', store: app.store })
+
+await subscriber.handler(changeUpdate('attendance', { id: 'a1', state: 'in' }, { id: 'a1', state: 'out' }), ctx)
+```
+
+**Build the event with a constructor, not with an object literal.** The
+constructors put the semantics in the name, which is the half a literal cannot
+give you:
+
+| | `op` | `old` | `new` |
+| --- | --- | --- | --- |
+| `changeInsert(t, row)` | `insert` | `null` | the row |
+| `changeUpdate(t, before, after)` | `update` | before | after |
+| `changeDelete(t, row)` | `delete` | the row | `null` |
+| `changeSoftDelete(t, row)` | **`update`** | `deletedAt: null` | `deletedAt` set |
+
+`changeSoftDelete` is the reason this exists. There is no `op: 'softDelete'` and
+there never will be — a soft delete is an ordinary update that sets `deletedAt`
+— so a test author who does not know that writes a delete, and the test passes
+against a stream the framework never emits. We shipped exactly that defect: a
+feature that keys off soft deletes was inert in production while its own tests
+were green, because they asserted against an event shape that does not exist.
+
+`ctx.store` has **no default and throws when touched**. Pass
+`makeTestContext().store` so the subscriber and the code under test share one; a
+silent empty store would let a subscriber reading the wrong table pass its test,
+which is the same silent-nothing the constructors exist to remove.
+
+`ctx.publish` is absent unless you pass one, mirroring the real context — where
+it is optional precisely so that reaching for it in an app that declares no
+event is a type error.
+
 ## Subject + tenant re-scoping
 
 `withSubject` and `withTenant` re-scope to a different principal for one block, sharing the **same** underlying data — so cross-subject reads exercise real tenant scoping, not a closure stub. This is how you prove isolation: write as one tenant, then assert another tenant can't see the row.