@levo-so/site-runtime 0.3.21 → 0.3.23

package/CHANGELOG.md

@@ -0,0 +1,352 @@
+# @levo-so/site-runtime
+
+## 0.3.23
+
+### Patch Changes
+
+- Two records in one URL segment. `levoParams(key, pattern, [siblings])` declares how a route's single param splits into several record variables, e.g. `/health-packages/<package>-in-<city>`:
+
+  - `const split = levoParams("packages_in_cities", "{$packages}-in-{$cities}")` goes on the route as `params: split`; the page reads `packages` and `cities` from `Route.useParams()`.
+  - The segment splits on its rightmost separator. A segment that does not fit is declined, so a plain sibling page (`$packages.tsx`) keeps serving `/health-packages/<package>`.
+  - `split.link(values)` is the `params` of a `<Link>` to the page (TanStack types it from every parsed param, so the segment alone does not compile); `split.segment(values)` is the string form.
+  - A plain variable beside the split in the same route is named in the third argument: `levoParams("c_in_d", "{$c}-in-{$d}", ["a"])`.
+  - Both arguments must be string literals, or top-level consts holding them: the platform reads the declaration out of the route file to enumerate the page's sitemap URLs and pairs each variable with the record binding whose `param` names it.
+
+  Loud failures for URL and binding mismatches:
+
+  - A record binding whose `param` names no param of the route throws on staging previews with the route's params listed, and logs on production sites while the record resolves to null as before.
+  - A `levoParams` key the route does not have is declined and reported once in the server log; the type check and the platform's publish check refuse it.
+  - Pattern errors (no variable, duplicate name, two variables with nothing between them, stray braces) throw when the route module initialises.
+
+  Requires the matching platform release for sitemap enumeration and publish validation; sites must pin this version for the builder AI to use the feature.
+
+  - @levo-so/core@0.3.23
+  - @levo-so/insights@0.3.23
+
+## 0.3.22
+
+### Internal
+
+- The package now ships its `CHANGELOG.md`, which Studio's runtime update hands to Levo AI.
+- The data client drops the `richtext` field type, which nothing used. Nothing to change in site code.
+
+## 0.3.21
+
+### Behaviour changes
+
+- **Collection forms take bookings on generated sites.** The booking flow — billing, booking card, payment — moved into the shared form library, so a `LevoForm` bound to a priced collection now goes on to billing and payment instead of saving the entry and stopping. It is styled with the form's own theme, so the site's brand colour and dark mode carry through into billing and the ticket.
+- Whether a submission is a booking or an enquiry is decided before billing. One with no matching price row is saved and gets the form's thank-you screen instead of a blank billing screen. When unsure (fixed price, older settings, a failed lookup) it is treated as a booking.
+- A failed booking keeps the visitor on billing to retry against the same entry, and the redirect after payment follows the form's success action.
+- Requests start their 30-second timeout when the call is made, not when the page loaded, so an action taken more than 30 seconds after page load no longer aborts before it is sent.
+
+### Fixed
+
+- The Stripe payment window keeps keyboard focus inside itself; Tab no longer walks onto the page behind it.
+
+### Internal
+
+- Dependency security updates. The upgrade's install picks them up; nothing to change in site code.
+
+## 0.3.20
+
+### Behaviour changes
+
+- **Event registration is one sheet.** `LevoEventRegister` opens a single scrolling sheet instead of a two-step modal: ticket choice with nothing preselected, a collapsible order summary, inline coupons, attendee details, payment, and an in-sheet confirmation with add-to-calendar that survives a reload. A failed payment returns to the filled-in form, and "Pay again" retries after a closed or failed payment. Signed-in visitors are prefilled. It uses the site's theme colours, so it follows the brand and dark mode.
+- Cashfree checkout for event registration, alongside Razorpay and Stripe.
+- The registration form's fields follow the event's `registration_fields`.
+
+### New
+
+- `LevoEventRegister` optional props `startsAt`, `endsAt` (the event's `starts_at` / `ends_at`, shown in the visitor's timezone and used for the calendar entry) and `eventUrl` (the joining link, attached to the calendar entry).
+- `?register=1` on a page URL opens the registration sheet on load — for campaign links and second calls to action.
+
+### Site changes (optional)
+
+- Where a page renders `LevoEventRegister` with the event record at hand, pass `startsAt={event.starts_at}`, `endsAt={event.ends_at}` and `eventUrl={event.url}` so the sheet shows the time and the calendar entry has the link. Without them it works as before.
+
+### Fixed
+
+- Restores the form fixes from 0.3.16, 0.3.17 and 0.3.18 that 0.3.19 was published without (see 0.3.19, Known issue).
+
+## 0.3.19
+
+### Breaking
+
+- **The runtime no longer adds the favicon.** `levoHead` (`createLevoHead`) used to emit `<link rel="icon">` from `site.json`; it no longer does, so a site that relied on it shows the browser's fallback icon (the React logo from `public/favicon.ico`, if that file is still there). Declare exactly one icon in `src/routes/__root.tsx`, in `head().links`, replacing any existing icon link:
+  `{ rel: "icon", href: site.icon?.location ?? "https://app.levo.so/favicon.ico" }`
+  with `import { LevoSiteProvider, site } from "@/lib/levo/runtime";`. If `src/lib/levo/runtime.tsx` has no `site` export (sites created before August), add it there: `export const site: ISiteJson = siteJson;`, importing `type ISiteJson` from `@levo-so/site-runtime`.
+- `ISiteMeta.icon` is removed. A `levoHead`/`pageHead` call that passes `icon` fails typecheck — delete the field.
+
+### Site changes (optional)
+
+- Add `{ title: site.name }` to the root route's `head().meta`, the fallback title for 404s.
+- Delete `public/favicon.ico`, `public/logo192.png`, `public/logo512.png` and `public/manifest.json` if nothing references them — leftovers from the React template.
+
+### Known issue
+
+- This build was published without the form fixes from 0.3.16, 0.3.17 and 0.3.18: forms behave as they did in 0.3.15. 0.3.20 restores them. Nothing to change in site code.
+
+## 0.3.18
+
+### Fixed
+
+- Forms (`LevoForm`, `LevoEntryForm`, `LevoProfileForm`, popup forms) hide fields the collection marks as not publicly viewable or submittable (`allow_public_view: false`, `allow_public_submit: false`), including sub-fields. A `hiddenFields` list that arrives after the first render is respected.
+
+## 0.3.17
+
+### Fixed
+
+- A phone, date-time or rich-text field revealed by form logic no longer blanks and resets the whole form.
+
+## 0.3.16
+
+### Fixed
+
+- Form logic: a section whose fields are all hidden no longer leaves an empty gap; step forms skip steps that would be empty; hiding is transitive (if A hides B, fields that depend on B hide too); hidden fields are cleared on submit.
+
+## 0.3.15
+
+### Fixed
+
+- Multi-language sites: hovering a link to an unprefixed path (`/pricing` instead of `/en/pricing`) froze the tab. `localeBeforeLoad` now redirects without a loop and keeps the query string. Nothing to change in site code.
+- `LevoBlogContent` renders self-hosted video blocks; YouTube and iframe embeds honour a percent width and left/center/right alignment; YouTube embeds keep 16:9 instead of a fixed 480px height; iframes are at least 100px tall.
+
+### Site changes (optional)
+
+- `src/components/language-switcher.tsx`, if present: put `key={locale}` before `{...linkProps}` on the `<a>`. Stops a React "unique key" warning on every page load.
+
+### Internal
+
+- Chat widget dependencies (`@assistant-ui/*`) bumped. The upgrade's install picks them up.
+
+## 0.3.14
+
+### Fixed
+
+- Links inside `LevoBlogContent` no longer carry `rel="nofollow"` or `rel="noreferrer"`; `rel="noopener"` is added only next to `target="_blank"`. Applies to posts already published.
+- Blockquotes inside blog content use the body text size and colour instead of a smaller muted grey — a visible change on posts with quotes.
+
+## 0.3.13
+
+### Breaking
+
+- The data client's blog and event reads now require their options bag: `blog.getAllBlogs(key, query, options)`, `blog.getSingleBlog(key, slug, options)`, `event.getAllEvents(seriesKey, query, options)`, `event.getSingleEvent(slug, options)`, where `options` is `{ workspace_id: string; params?: Record<string, string> }`. Only code that calls the client from `useLevoSite()` directly is affected — `useLevoSource`, `useLevoRecord` and route `dataSources` are not. Those calls were already failing at runtime (events answered 400, blog lists came back empty).
+
+### Site changes
+
+- Record bindings take `param`, the route param they read, spelled exactly like the `$segment` in the route's file name: `{ mode: "record", module: "blog", identifier: "so_levo_blog", param: "slug" }`. **Required on a route with two or more `$params`** (e.g. `src/routes/stores/$state/$city.tsx`): without it the loader looks for `params.slug`, finds nothing, and the page renders with no server-side data, title or share image. A route with a single `$param` falls back to it, so `param` is optional there.
+
+### Fixed
+
+- Blog and event data sources send the workspace, so event pages stop answering 400 and blog lists stop coming back empty.
+- A detail route whose param isn't `slug` (e.g. `/legal-events/$events`) now prefetches its record, so it gets its per-record title, description and share image.
+- Visitor chat: tables in replies get a "Copy table" button.
+
+## 0.3.12
+
+### Breaking
+
+- **`LevoRichText` is renamed `LevoBlogContent`**, and its subpath moves: `@levo-so/site-runtime/rich-text` → `@levo-so/site-runtime/blog-content`; `ILevoRichTextProps` → `ILevoBlogContentProps`. Same props (`content` plus div attributes). No alias: the old import fails typecheck. Fix: `Grep` for `LevoRichText` and `site-runtime/rich-text`, then rename the import and the tag. Where it wraps a plain string (a title, an excerpt, a description), remove the wrapper and render the string instead — the component is only for a stored editor document, i.e. a blog post's `content` or a rich-text collection field.
+
+### New
+
+- `useLevoSearch({ limit?, debounceMs?, hotkey? })` — site-wide search behaviour: `query`/`setQuery`, debounced `results`, `isLoading`, `error`, `isEmpty`, and a ⌘K open state (`isOpen`, `open`, `close`). Renders nothing; must sit under `LevoSiteProvider`. Each result is `ILevoSearchResult { content_type, content_id, title, description, url, thumbnail, score }`.
+- `LevoForm` optional props: `defaultValues` (prefill by collection field key), `onSuccess(result)` and `onError(error)`, `showSuccessScreen={false}` (keep the form instead of the thank-you card), `disabled`. Types `ILevoFormSubmitResult`, `ILevoFormSuccessConfig`.
+- `LevoSiteProvider` takes `analytics?: boolean` (default `true`). Sites created from this version pass `analytics={import.meta.env.PROD}` in `src/lib/levo/runtime.tsx` so previews stop counting as visits.
+
+### Site changes (optional)
+
+- Sites created from this version ship `src/components/search/SiteSearch.tsx`, `src/components/access/LoginModal.tsx` and `src/components/access/UserMenu.tsx`. An older site does not have them — never import one without checking it exists; build the feature from the hooks instead.
+
+### Behaviour changes
+
+- Inside the Studio editor preview, the chat launcher and the "Made with Levo" badge are hidden. The preview URL and the live site are unchanged.
+- The editor can force a gated page's outcome (granted, sign-in, blocked) to design it. On the live site the real session still decides, and the data behind the gate stays protected.
+
+## 0.3.11
+
+### Behaviour changes
+
+- Analytics now creates visitor ids in the browser and sets first-party cookies `id_i_cd` (device) and `id_i_cs` (session) plus localStorage `lv_insights_identity`; `lv_aud_*` and `lv_insights_sf` are no longer written. Update any cookie banner or privacy page that names cookies. No code changes.
+
+## 0.3.10
+
+### New
+
+- Data sources read blog categories, tags and authors (`module: "blog_category" | "blog_tag" | "blog_author"`, `identifier` = the parent blog's key) and community forum posts (`module: "community"`, `identifier` = the forum key). Type `ILevoSourceModule`.
+- `LevoRichText` from `@levo-so/site-runtime/rich-text` — renamed in 0.3.12; do not use this name.
+
+### Behaviour changes
+
+- `LevoSiteProvider` shows a small "Made with Levo" badge in the bottom-right corner when the workspace's plan requires branding (`site.json` → `feature_flag.branding`). Remove any hand-built Levo badge so it doesn't show twice.
+- `@levo-so/site-runtime/setup.css` now includes the blog-content prose styles.
+- Visitor chat shows when each message was sent ("9:42 AM", "Aug 19 · 9:42 AM").
+
+### Site changes (optional)
+
+- `__root.tsx` `head().links`: `{ rel: "preconnect", href: "https://static.levocdn.com" }` makes Levo-hosted images start loading sooner.
+
+## 0.3.9
+
+### New
+
+- Multi-language sites. Inert until the workspace has two or more locales; single-language sites are unaffected.
+  - `@levo-so/site-runtime/start` (new subpath): `createLocaleMiddleware(config, routeTree)`, used in `src/start.ts`.
+  - `readLocaleConfig(site)`, `localeBeforeLoad(config, routeTree)`, `SiteLocaleProvider`, `LocaleHreflang`, `useUrlLocale(config)`, `useLocale()`, `useLanguageOptions()` (link props for a language switcher).
+  - `ISiteJson` gains `locales` and `default_locale`.
+- Do not add this wiring during an upgrade. It is only needed once a workspace adds a second language, and switching it on moves every URL under a language prefix. When wiring it, never import `@/routeTree.gen` into `__root.tsx` — the import cycle makes every server render fail.
+
+### Behaviour changes
+
+- Canonical URLs drop the trailing slash (`/blog/` → `/blog`; the root keeps its `/`). Visible to search engines.
+- New-entry forms prefill the collection's default values. Clearing a relation field now saves (it is sent as empty instead of left out).
+
+### Internal
+
+- Tiptap bumped to 3.30, Stripe and Razorpay pinned; new optional peer `@tanstack/react-start`, which every site already has. The upgrade's install picks them up.
+
+## 0.3.8
+
+### New
+
+- Members-only pages (page gating):
+  - `useLevoAccess({ id, access })` — the page gate: `state` (`checking | granted | blocked`), `code`, `rule`, `authMethods`, `recheck`. Stays closed on any failure.
+  - `useLevoAuth()` (the visitor's session: `account`, `isLoggedIn`, `isLoaded`, `refresh`, `signOut`), `useLevoLogin()` (`sendCode`, `resendCode`, `verifyCode`, `sendMagicLink`, each returning `{ ok, data | error }`), `useLevoOAuth(...)` (Google, Microsoft, LinkedIn popup sign-in), `useLevoOtpInput(...)`.
+  - `LevoEntryForm` (request access to a collection), `LevoProfileForm` (complete the member profile).
+  - Validators `isValidEmail`, `isValidOtp`, `isValidPhone`, `normalizePhone`; `LEVO_OTP_LENGTH`.
+- The loader from `createLevoLoader(site)` takes the route's meta as an optional second argument: `loader: levoLoader(dataSources, meta)`. A gated page then skips its server-side prefetch, so its data never reaches a visitor the gate would refuse.
+
+### Site changes (only for gated pages)
+
+- Sites created from this version ship the gate UI in `src/components/access/` (`AccessGate.tsx`, `LoginCard.tsx` and the rest). An older site does not have that folder — never import from `@/components/access/` without checking it exists; build the gate from `useLevoAccess` and `useLevoLogin` instead.
+
+### Fixed
+
+- A form with a phone, date-time or rich-text field no longer blanks the page while those fields load.
+
+## 0.3.7
+
+### Behaviour changes
+
+- Visitor chat: on a site with several chat agents, the agent follows the page while the conversation carries over; reloading the page starts a fresh conversation; suggested questions come from the current agent and fill the input instead of sending; while an answer streams, Stop is the only action.
+- Event registration (`LevoEventRegister`): the tax/GST block is hidden when nothing is payable, and the dialog scrolls inside itself on short screens.
+- Popups: a redirect popup's cover image is clickable; popup content loads when the popup opens.
+
+### Internal
+
+- Chat widget dependencies (`@assistant-ui/*`) move from 0.12 to 0.15. The chat panel breaks on first open if the site's lockfile keeps the old versions; the upgrade's install picks up the new ones.
+
+## 0.3.1
+
+### Patch Changes
+
+- 88218da: Sites now start insights, expose the runtime handles, and carry their page id.
+
+  - `LevoSiteProvider` calls `insights.init()` after mount. Nothing on a code-routed site did — Levo-hosted pages get it from `LevoPage`'s `LevoInsightsPage` — so `$isIdentityContextReady` never flipped and every store-only consumer (popup triggers, DOM trackers) waited forever. Popups were silently dead on generated sites.
+  - `window.levo_client` / `window.levo_insights` are set on generated sites, matching what `LevoPage` exposes on Levo-hosted ones.
+  - Page identity flows route → runtime: `meta/<route>.json`'s `id` (new `IPlatformMetaFile.id`) is stamped into the head by `levoHead` and read back by the provider on mount and on every client navigation (`readPageId` / `PAGE_ID_META`, both exported). It feeds analytics `page_id` and `LevoPopups`' new `pageId` prop, which makes page-bound popup targeting work on code-routed sites. Sites whose meta files carry no id are unaffected — URL-path targeting behaves as before.
+
+### Patch Changes
+
+- insights and popup fixes
+
+## 0.3.0
+
+### Minor Changes
+
+- 1e929c2: Inspector: selection captures for the editor's AI chat.
+
+  - `capture-selected` message — rasterizes the currently selected element to a PNG data URL (html-to-image, lazy-loaded chunk) and replies `capture-result`.
+  - Select-mode marquee drag (region select): press-drag draws a dashed rubber-band; release reports `region-selected` with the dragged rect, the topmost source-stamped elements substantially inside it (capped at 12), and a PNG of exactly that area. Sub-threshold presses remain single-element click picks; Esc mid-drag cancels the marquee only. Driven by pointer events (the swallow layer's `pointerdown` preventDefault suppresses all compatibility mouse events — mouse-based drag listeners never fire in select mode). Pointer capture at drag activation makes the gesture edge-tolerant: overshooting the iframe boundary clamps the marquee to the frame instead of cancelling, and releasing outside still finalizes.
+  - Region highlights: after a drag, every included element gets a persistent green ring (fixed pool, part of the inspector's own overlay set) — repositioned on scroll/resize, suppressed in text mode, cleared by the same paths as the single-pick ring (new pick, clear-selection, route change).
+  - Correct capture backgrounds: renders are subtree-only, so ancestor-painted backgrounds used to come out transparent ("wrong bg"). Element captures now fill with the effective ancestor background color; region captures climb to the nearest background-painting ancestor as the render root (bounded at 4 viewport-areas) so crops include real gradient/image backgrounds, with the color fill as fallback. The intermediate region raster is capped at a 4000px longest edge so a small drag inside a large painted section can't spike memory or stall the preview.
+
+### Patch Changes
+
+- select element ss
+
+## 0.2.3
+
+### Patch Changes
+
+- dark mode, popups, site agents
+
+## 0.2.2
+
+### Patch Changes
+
+- image edit and better shortcut support
+
+## 0.2.1
+
+### Patch Changes
+
+- fa254dc: Studio v3 sites can now render events and take registrations.
+
+  - Data sources: `module: "event"` works with `useLevoSource` (events in a series, keyed
+    by the series id) and `useLevoRecord` (one event detail page by slug).
+  - New `LevoEventRegister` component — a self-contained ticket booking + payment widget
+    (Razorpay by default, Stripe Embedded Checkout when the booking API returns
+    `provider: "stripe"`). Generated event pages drop this in and never rebuild the flow.
+  - Adds `@stripe/stripe-js`, `@stripe/react-stripe-js`, `react-razorpay` dependencies and
+    `lucide-react` + `react-dom` peer dependencies. The registration dialogs are built on
+    Base UI (`@base-ui/react`, an optional peer) for focus trapping, scroll lock, and
+    accessible dialog semantics.
+
+- fa254dc: Collection-backed forms. Generated sites can now collect submissions into a collection.
+
+  - New `mode: "form"` data source — the route loader prefetches the collection SCHEMA
+    (`getCollectionByIDExpanded`) SSR via `prefetchLevoSources`, and `useLevoForm(config)`
+    reads it from the warm cache.
+  - New `LevoForm` component — renders the collection's fields, validates, submits, shows a
+    success screen, and handles captcha. It reuses the shared `CollectionFormRenderer`, which
+    resolves its client from `@levo-so/react`'s `useLevo()` context. `LevoSiteProvider` now
+    mounts that context at the site root (it delegates to `@levo-so/react`'s `LevoProvider`,
+    a trivial SSR-safe context after the P5 SDK diet), so the renderer works with no per-form
+    provider bridge. `useLevoSite`/`useLevoInsights` are null-safe re-exports of
+    `@levo-so/react`'s `useLevoClient`/`useLevoInsights`.
+  - `LevoForm` auto-themes to the site: it maps the renderer's full color contract onto the
+    starter's semantic tokens (`--color-brand`, `--color-ink`, `--color-border`…) via levocn's
+    `inlineBaseTheme`, so a form matches the brand out of the box and re-skins when `theme.css`
+    changes. Its prop surface is intentionally narrow (`source`, `submitLabel`, `hiddenFields`,
+    `formVariant`, `successConfig`, `theme`, `className`) rather than exposing the renderer's
+    full context; `theme` allows per-form color/radius overrides.
+  - The form renderer (`@levo.libraries/react-collection` + `editor-core` + `levocn`) and the
+    `@levo-so/react` client context it depends on are now BUNDLED into this package's dist
+    (mirroring how `@levo-so/studio` ships). A consuming site installs only
+    `@levo-so/site-runtime` from public npm — no private registry, and `@levo-so/react` never
+    appears as a dependency. The ~40 public leaf deps (tiptap, yup, react-select, sonner…) are
+    hoisted into this package. Bundled styles ship as `@levo-so/site-runtime/setup.css`.
+  - Build change: switched from per-module output to studio-style bundled output
+    (`publishConfig.directory: "dist"`, generated `dist/package.json`, rolled-up types).
+
+- full cleanup
+- Updated dependencies [fa254dc]
+- Updated dependencies
+  - @levo-so/core@0.2.1
+  - @levo-so/insights@0.2.1
+
+## 0.2.0
+
+### Minor Changes
+
+- 54e5118: Package the scaffold contract so starters stay thin shims: `createLevoHead(siteJson)` —
+  each route imports its own `meta/<route>.json` (`@meta/` alias) and wires
+  `head: levoHead(meta)`; composes the platform meta keys (incl. `ld_json`, `canonical`,
+  `twitter_card`, `head_code`, `disable_indexing`) with site.json fallbacks
+  ("Page name | Site name") into the document head. Plus `createLevoLoader` (the SSR
+  data-source route loader) and `siteConfigFromJson` (site.json → ILevoSiteConfig). The
+  starter's single `src/lib/levo/runtime.tsx` shim only feeds in `site.json`; every future
+  behavior change ships by bumping this package.
+
+### Patch Changes
+
+- updated meta folders
+
+## 0.1.113
+
+### Patch Changes
+
+- Updated dependencies [d885aa0]
+  - @levo-so/core@0.1.113
+  - @levo-so/insights@0.1.113

package/index.d.ts

@@ -883,6 +883,51 @@ export declare interface ILevoOtpSlot {
     };
 }
 
+/**
+ * One split segment, declared once: the route's `params` option IS this object, and every
+ * link to the route reuses the same const, so the pattern is never spelled twice.
+ * `TSiblings` names the route's other required params, `never` when the segment is the only
+ * one (see `levoParams`).
+ */
+export declare interface ILevoParams<TSegment extends string, TPattern extends string, TSiblings extends string = never> {
+    /**
+     * TanStack's `params.parse`: the variables split out of the segment beside the raw key and
+     * the siblings, or `false` for a segment the pattern does not fit, which declines the route
+     * so the sibling route with no pattern serves the URL. Throws when the key is not a param of
+     * the route at all (the first argument misspells the file's `$param`): see `parse` below.
+     */
+    parse: (raw: Record<TSegment | NoInfer<TSiblings>, string>) => ILevoParsedParams<TSegment, TPattern, TSiblings> | false;
+    /**
+     * The segment the values compose (`"full-body-in-mumbai"`), for a string href: a JSON-LD
+     * url, a sitemap-style index. A missing or empty value throws: a link with a hole is a bug,
+     * not a URL.
+     */
+    segment: (values: Record<ILevoPatternVars<TPattern>, string>) => string;
+    /**
+     * The `params` of a `<Link>` to the route: the values plus the composed segment under the
+     * raw key, with the sibling values passed through so a `<Link to="/$a/$c_in_d">` gets `a`
+     * beside the segment. Exists because TanStack types `Link params` from the route's PARSED
+     * params, so the variables are required beside the segment and the segment alone does not
+     * compile. Throws for a missing or empty value, as `segment` does.
+     */
+    link: (values: Record<ILevoPatternVars<TPattern> | TSiblings, string>) => ILevoParsedParams<TSegment, TPattern, TSiblings>;
+}
+
+/**
+ * What `parse` returns and `link` composes: the route's raw segment param (TanStack's
+ * parsed-params type must keep it), the route's other required params named as siblings
+ * (TanStack types the route's params from this alone, so a sibling not named here drops out
+ * of the route's types), plus one string per pattern variable.
+ */
+export declare type ILevoParsedParams<TSegment extends string, TPattern extends string, TSiblings extends string = never> = Record<TSegment | TSiblings, string> & Record<ILevoPatternVars<TPattern>, string>;
+
+/**
+ * The variable names of a pattern as a union of literals:
+ * `ILevoPatternVars<"{$packages}-in-{$cities}">` is `"packages" | "cities"`.
+ * A pattern that is not a literal has no inferable names (`never`).
+ */
+export declare type ILevoPatternVars<TPattern extends string> = TPattern extends `${string}{$${infer TName}}${infer TRest}` ? TName | ILevoPatternVars<TRest> : never;
+
 export declare interface ILevoPopupsProps {
     /**
      * The site's id (`site.json` `id`) — scopes the active-popups fetch. Absent → the
@@ -921,7 +966,9 @@ export declare interface ILevoRecordConfig {
      * Route param this binding's slug comes from — `"slug"` on `/blog/$slug`, `"events"` on
      * `/legal-events/$events`. Every generated record binding carries it: it is the mapping a
      * multi-param route needs, since with two variable segments nothing else in the file says
-     * which binding fills which slot. Round-tripped through the editor binding like the rest.
+     * which binding fills which slot. On a `levoParams` page it names one pattern variable
+     * (`"packages"` for `{$packages}-in-{$cities}`), which is how the platform pairs each variable
+     * with a collection. Round-tripped through the editor binding like the rest.
      *
      * Optional only for the pages written before it existed — see {@link recordSlug}.
      */
@@ -1755,6 +1802,8 @@ export declare const LevoEventRegister: ({ eventID, title, external, buttonText,
  */
 export declare const LevoForm: React.FC<ILevoFormProps>;
 
+export declare const levoParams: <TSegment extends string, TPattern extends string, TSiblings extends string = never>(key: TSegment, pattern: TPattern, _siblings?: readonly TSiblings[]) => ILevoParams<TSegment, TPattern, TSiblings>;
+
 /**
  * Mounts the site's popups, wired from `site.json`. Rendered once from the scaffold's
  * `__root` (via the `SitePopups` shim), inside `<LevoSiteProvider>` — `PopupLoader` reads
@@ -1936,6 +1985,12 @@ export declare const parseRawHead: (raw: string) => IComposedHead;
  * source resolves to null so it doesn't blank the whole page — the hook surfaces that
  * binding's error while the rest render.
  *
+ * One failure is NOT absorbed outside production: a record binding whose `param` names no
+ * param of the route. That is a wiring mistake in the page (never a transient fetch error),
+ * it renders as a not-found record that no one can tell from a bad slug, and the preview is
+ * where it gets fixed — so there the loader rejects with the message and the route's error
+ * boundary shows it. See the branch below for what "preview" can mean here.
+ *
  * Returns the fetched values keyed by source key (records as the record object, lists as
  * `{data, meta}`). The route loader returns this map, making it the route's `loaderData` —
  * which `levoHead`'s dynamic config reads for per-record titles/descriptions/share images.