@v-office/website-headless 0.1.1 → 1.0.0

package/README.md

@@ -1,85 +1,2208 @@
 # @v-office/website-headless
 
-The **behavior layer** for v-office websites. The invariant: **this package
-never contains UI.** It is `.ts` only. Imported UI lives one layer up in
-`@v-office/website-components` and renders over the hooks here; the
-structural requirements that UI must satisfy (`checkout/structure.ts`) live
-HERE, so a site's own UI is held to the same contract.
+The **behaviour layer** of v-office websites: stores, pure rules, SDK runners, models, constants and
+the part vocabularies that something other than styling depends on. It never renders. A site uses it
+through `@v-office/website-components` (React surfaces over these stores) or builds its own UI over
+the same stores and is held to the same rules: the quote, checkout and contact flows, the insurance
+document gate and the checkout's structural requirements live here, not in a component.
 
 ```
 @v-office/sdk-core           domain contracts + PMS adapters
 @v-office/website-sdk        website facade (static + live namespaces)
-@v-office/website-headless   ←  THIS: orchestration hooks, validation, legal
-                             gates, enhancement engines
-@v-office/website-components imported UI over these hooks (a site may copy and own it)
+@v-office/website-headless   ←  THIS: stores, rules, SDK runners, models, enhancement engines
+@v-office/website-components imported UI over these stores (a site may build its own instead)
 userland                     pages, brand components, tokens, copy
 ```
 
-## Entry points
+**What it is not.** No React, no markup, no copy (stores take `messages` and return kinds and
+numbers), no `window` or `document` in the `.` entry, no SDK built on its own initiative, and no
+site-specific default: a difference between sites is a documented option whose default is right for
+a site that never thought about it. Facts about the business (routes, the address decision, the
+favourites namespace, the backend) have no default at all.
 
-| Import                       | Contents                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `@v-office/website-headless` | Framework-free runtime: `createCheckoutFlow` — the whole checkout machine (stay → quote → selections → § 7 gate → book → pay) as a store with `getState` / `subscribe` / actions / `update` / `start` / `dispose`; `createStore`, the primitive every flow here builds on; `fetchQuote` + the quote view model, `book()`/`pay()` runners, the payment-return snapshot, validation rules, `CHECKOUT_PARTS` + `assertCheckoutStructure`, `logSdkFailure` |
-| `…/enhance`                  | Progressive enhancement for server-rendered markup: card image strips, history-backed content overlays, the rental gallery's layered viewer. They bind site markup and own none of it                                                                                                                                                                                                                                                                  |
+## Contents
 
-The flows are stores: a UI calls `getState()`, `subscribe(listener)` and the
-actions, and feeds its inputs through `update()`. No framework code lives here.
-`@v-office/website-components` (React) ships `useCheckoutFlow` for React sites
-that render their own booking UI; a site that wants neither writes the binding
-itself — it is this small:
+- [Install and entry points](#install-and-entry-points)
+- [Wiring a site](#wiring-a-site)
+- [Stores](#stores)
+- [Conventions and shared types](#conventions-and-shared-types)
+- [Search form](#search-form)
+- [URL parameters](#url-parameters)
+- [Guests](#guests)
+- [Search store and live search](#search-store-and-live-search)
+- [Offers](#offers)
+- [Results map](#results-map)
+- [Rental catalogue and detail model](#rental-catalogue-and-detail-model)
+- [Cards and facts](#cards-and-facts)
+- [Showcase selectors](#showcase-selectors)
+- [Quote flow and availability](#quote-flow-and-availability)
+- [Checkout flow](#checkout-flow)
+- [Contact form](#contact-form)
+- [Countries](#countries)
+- [Legal documents](#legal-documents)
+- [Favourites](#favourites)
+- [Shared helpers](#shared-helpers)
+- [Enhance engines](#enhance-engines)
+- [Part vocabularies](#part-vocabularies)
+- [Migrating from 0.1.x](#migrating-from-01x)
+- [Development](#development)
+
+## Install and entry points
+
+```bash
+pnpm add --save-exact @v-office/website-headless @v-office/website-sdk
+```
+
+- **The only peer is `@v-office/website-sdk >=2.25.0 <3`.** There is no runtime dependency. Sites
+  pin exact versions; updates arrive through fleet rollouts.
+- `maplibre-gl` is not a dependency: the map engines take a loader (`() => import("maplibre-gl")`)
+  from the caller.
+
+| import                               | runs                  | contents                                                                                                                                         |
+| ------------------------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@v-office/website-headless`         | Node (build), browser | every module below; nothing touches `window`/`document` at import, nothing is registered on `globalThis` until a page-shared instance is claimed |
+| `@v-office/website-headless/enhance` | browser only          | `enhance(root, options)` and the binders it composes over server-rendered markup, plus the MapLibre engines                                      |
+
+`ENHANCE_PARTS` and `GATE_MARKERS` are exported from both entries, so a build can render the markup
+contract without importing browser code.
+
+The documented exceptions to "no DOM in `.`" take what they need as an argument or only touch the
+browser when called: `assertCheckoutStructure(root)` takes a DOM root; `browserStorage()`, the
+favourites store and the payment-return snapshot use Web Storage and fail soft without it;
+`loadRentalIndex` and `loadRentalFacts` call `fetch`; `resultsQueryFlagScript()` returns script
+source for the page's `<head>`.
+
+## Wiring a site
+
+### The SDK setup
+
+Every SDK-using surface takes one plain-data `SdkSetup` (`{ config, options? }`). A site writes it
+once in `src/data/sdk.ts`:
+
+```ts
+import { sdkConfigFromEnv, type SdkSetup } from "@v-office/website-headless";
+
+export const SDK: SdkSetup = {
+  // Each name spelled out: Vite inlines only the `import.meta.env.NAME` it sees, so
+  // `import.meta.env` passed whole can arrive without them in a build.
+  config: sdkConfigFromEnv({
+    CMS_BACKEND: import.meta.env.CMS_BACKEND,
+    CMS_STAGE: import.meta.env.CMS_STAGE,
+    HUB_API_KEY: import.meta.env.HUB_API_KEY,
+    HUB_GRAPHQL_URL: import.meta.env.HUB_GRAPHQL_URL,
+    HUB_V0_API_BASE_URL: import.meta.env.HUB_V0_API_BASE_URL,
+    HUB_V1_API_BASE_URL: import.meta.env.HUB_V1_API_BASE_URL,
+    IMAGE_PROXY_BASE_URL: import.meta.env.IMAGE_PROXY_BASE_URL,
+    VOFFICE_LOCAL_DEV_ACCESS_TOKEN: import.meta.env.VOFFICE_LOCAL_DEV_ACCESS_TOKEN,
+    VOFFICE_API_ENDPOINT: import.meta.env.VOFFICE_API_ENDPOINT,
+    VOFFICE_SEARCH_ENDPOINT: import.meta.env.VOFFICE_SEARCH_ENDPOINT,
+    VOFFICE_IMAGE_BASE_URL: import.meta.env.VOFFICE_IMAGE_BASE_URL,
+  }),
+  // Only the options the site uses: the setup is serialized into every island.
+  options: { translationOverrides: {} },
+};
+```
+
+- `sdkConfigFromEnv(env)`: The fleet's env names → `SdkConfig`. `env` is an `EnvRecord`; it never
+  reads `process.env`; pass a literal that names each variable (above), or `process.env` in a Node
+  script. Only non-empty strings count (Vite's boolean flags are ignored). Throws one `SdkEnvError`
+  naming every missing or conflicting variable at once.
+- `SDK_ENV`: The env names (a platform contract: the AI Studio builder reads `HUB_API_KEY`; renaming
+  one is a major).
+- `SdkEnvError`: `missing: string[]`, `conflicting: string[]`; the message names variables, never a
+  value.
+- `sdkConfigFor({ backend, stage, token })`: `SdkConfigForInput` → a full config with the platform's
+  public endpoints. Spread extras on top:
+  `{ ...sdkConfigFor(…), facilityObjectGroupRelationAttributeId: 123 }`.
+- `VOFFICE_ENDPOINTS`, `HUB_ENDPOINTS`: `VofficeEndpointTable` / `HubEndpointTable`: the public
+  https endpoints (`VofficeEndpoints`, `HubEndpoints`) per `Stage` (`"development"`, `"production"`;
+  `STAGES` lists both).
+- `SdkConfig`: The SDK's own `WebsiteSDKConfig`, with `backend` explicit on v10. A site with an
+  unusual setup (a dev proxy) writes the literal.
+- `SdkOptions`: The SDK options as data (`translationOverrides`, `customAttributes`,
+  `rentalHighlightPrioritization`, …), without `searchAllRentalsAtOnce` (that is `SdkMode`).
+- `SdkSetup`: `{ config: SdkConfig; options?: SdkOptions }`.
+- `Backend`, `Stage`, `Locale`: `"v9" | "v10"`; `"development" | "production"`; the SDK's
+  `"de-DE" | "en-US"` (there is no third locale).
+
+`sdkConfigFromEnv` rules, in order:
+
+1. `CMS_BACKEND` must be `v9` or `v10`. There is no silent default.
+2. The backend's token is required: `HUB_API_KEY` (v9, the public be-on key) or
+   `VOFFICE_LOCAL_DEV_ACCESS_TOKEN` (v10).
+3. With `CMS_STAGE` (`development` | `production`) set, the platform endpoints of that stage are
+   used and the URL variables must be absent (two sources for one value is an error, not a merge).
+4. Otherwise every URL variable of the backend is required: v9 `HUB_GRAPHQL_URL`,
+   `HUB_V0_API_BASE_URL`, `HUB_V1_API_BASE_URL`, `IMAGE_PROXY_BASE_URL`; v10 `VOFFICE_API_ENDPOINT`,
+   `VOFFICE_SEARCH_ENDPOINT`, `VOFFICE_IMAGE_BASE_URL`.
+
+### Which SDK instance
+
+The package constructs an SDK only when asked. Every runner and store takes the SDK as its first
+argument, as an `SdkSource`: an instance, or a getter (`() => WebsiteSdk | Promise<WebsiteSdk>`).
+Every store calls a getter once, on its first request, and again only after a failed resolve, so a
+getter that constructs (a lazy `shareSdk` claim) constructs once per store.
+
+- `createSdk(setup, mode?)`: Build time and scripts. The caller owns the instance: every build-time
+  loader takes the same one (the API allows 1 request per second per instance), and the caller
+  disposes it (`await sdk.dispose()`) after the last loader, in a `finally`, so a failed loader
+  releases it too.
+- `shareSdk(setup, mode?)`: Browser surfaces. Returns a `SharedSdk` (`{ sdk, release() }`): every
+  claim with an equal setup and mode (compared as key-sorted JSON) gets the page's same instance, so
+  one 1 req/s queue and one cache serve every surface. The last `release()` disposes it, unless a
+  new claim arrives within the same task (a React StrictMode remount keeps it).
+- `loadSharedSdk(setup, mode?)`: `shareSdk` with the SDK imported on first call (a dynamic
+  `import()`): a page whose only SDK use is a submit (a contact form) ships no SDK code up front.
+  Resolves to the instance `shareSdk` holds for the same setup.
+- `resolveSdk(source)`: The instance behind an `SdkSource` (a promise). Call it once per call site
+  and keep the result.
+- `SdkMode`: `"default"` (paged search and `mapSearch`) or `"all-rentals-at-once"`
+  (`searchAllRentalsAtOnce`: at most 100 rentals priced in one call, no cursor, no `mapSearch`). A
+  store or walker over such an instance takes the same value as `sdkMode`.
+- `WebsiteSdk`, `SdkSource`: A constructed SDK (either backend); what every store takes first.
+- `describeSdkError(error)`: A failed SDK call and its whole `cause` chain as indented JSON (stacks
+  skipped). `console.error(error)` does not print the cause, which is where the backend's reason is.
+- `logSdkFailure(scope, error)`: `console.error("[sdk] <scope> failed:", description)`, tagged by
+  SDK operation (`"search.search"`, `"contact.submit"`). Every runner in this package already logs
+  through it.
 
 ```ts
-import { useEffect, useRef, useSyncExternalStore } from "react";
 import {
-  createCheckoutFlow,
-  type CheckoutFlow,
-  type CheckoutFlowOptions,
+  createSdk,
+  fetchLegalDocuments,
+  loadRentalCatalogue,
+  resolveFilters,
+  shareSdk,
 } from "@v-office/website-headless";
 
-export function useCheckoutFlow(options: CheckoutFlowOptions) {
-  const ref = useRef<CheckoutFlow | null>(null);
-  ref.current ??= createCheckoutFlow(options);
-  const flow = ref.current;
-  useEffect(() => flow.update(options));
-  useEffect(() => {
-    flow.start();
-    return () => flow.dispose();
-  }, [flow]);
-  const state = useSyncExternalStore(flow.subscribe, flow.getState, flow.getState);
-  return { ...state, ...flow };
+// Build time: one instance for every loader, disposed after the last one.
+const sdk = createSdk(SDK);
+try {
+  const rentals = await loadRentalCatalogue(sdk, { locale: "de-DE" });
+  const filters = resolveFilters(
+    await sdk.static.filter.getFilters({ locale: "de-DE" }),
+    FILTER_SPEC,
+  );
+  const legal = await fetchLegalDocuments(sdk, "de-DE");
+  // … the plain results go to the pages; no page builds an SDK of its own
+} finally {
+  await sdk.dispose();
+}
+
+// Browser: claim the page's instance, release it when the surface goes.
+const shared = shareSdk(SDK);
+// … createSearchStore(shared.sdk, …), createQuoteFlow(shared.sdk, …)
+shared.release();
+```
+
+Two surfaces whose setups differ in any option get two instances, each with its own rate limit. Pass
+the one `SDK` constant everywhere.
+
+### Site constants
+
+A site writes each decision once and passes the constant to every surface that needs it, so two
+surfaces cannot disagree.
+
+| constant          | type                                                        | passed to                                                      |
+| ----------------- | ----------------------------------------------------------- | -------------------------------------------------------------- |
+| `SDK`             | `SdkSetup`                                                  | every SDK-using surface                                        |
+| `SEARCH_CONTRACT` | `SearchContract` (`backend`, `nightRangeSearch`, `aliases`) | search form, search store, offer chips                         |
+| `GUESTS`          | `GuestOptions` (limits, child age band, default adults)     | search form, quote flow, checkout flow                         |
+| `DAY_PRICES`      | `DayPrices`                                                 | the booking calendars (`dayPriceLabel`)                        |
+| `POLICY_CHOICE`   | `PolicyChoiceMode`                                          | quote flow and checkout flow (`policyChoice`)                  |
+| `BOOKABLE`        | `BookableFrom`                                              | the search form's `dates.bookable` and the quote's notice      |
+| `ADDRESS`         | `RentalAddressMode`                                         | `rentalAddressLine` (the rental heading and map)               |
+| `FAVORITES_KEY`   | `string` from `favoritesStorageKey(namespace)`              | `enhance()`, `createFavorites`/`acquireFavorites`, every heart |
+
+`@v-office/website-components` adds `CARD` (`RentalCardOptions`, which extends `CardModelOptions`)
+and `VOICE` (`Voice`).
+
+### Build time and browser
+
+Everything in `.` runs in both places, but some calls belong to one of them:
+
+- **Build time** (they spend rate-limited requests or need full ICU): `loadRentalCatalogue`,
+  `fetchRentalFlags`, `resolveSearchGroups`, `measureFilters`, `findOfferWindows`,
+  `findCampaignStart`, `fetchLegalDocuments`, `countryOptions`, `rentalIndexEntries`, `cardSource`,
+  `rentalFactsMap`, `buildShowcaseGroups`, `resolveFilters`. Their results are plain JSON and are
+  passed to islands as props.
+- **Browser**: the stores (`createSearchForm`, `createSearchStore`, `createQuoteFlow`,
+  `createCheckoutFlow`, `createContactForm`, `createFavorites`), `loadRentalIndex`,
+  `loadRentalFacts`, `readPaymentReturn`, and all of `./enhance`.
+
+## Stores
+
+Every flow is a store: a UI reads `getState()`, subscribes, and calls actions. The state object is a
+new reference on every change and the same reference otherwise, so it works as a React external
+store, a Vue `shallowRef`, a Svelte store or a plain listener.
+
+| export                       | what it is                                                                                                              |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `Store<S>`                   | `getState(): S` and `subscribe(listener): Unsubscribe`. A listener is not called for the state current at subscription. |
+| `WritableStore<S>`           | Adds `setState(next \| (prev) => next)`; the same reference is a no-op. `S` is never a function itself.                 |
+| `createStore(initial)`       | The primitive every flow builds on (a custom UI may use it for its own state).                                          |
+| `Listener<S>`, `Unsubscribe` | The listener and its removal (calling it twice is harmless).                                                            |
+
+Conventions every store follows:
+
+- `create<Thing>(sdk?, options)` returns the store plus its actions and, where it holds timers or
+  subscriptions, a `dispose()` that stops them and drops late answers. A store never disposes the
+  SDK.
+- Options are plain data (an island receives them as props). Stateful factories take
+  `now?: () => Date` for tests and read it when needed; pure rules take `today?: IsoDay`.
+- `acquire<Thing>(key, create)` gives every island on the page the same instance through one
+  ref-counted registry on `globalThis[Symbol.for("@v-office/website-headless/<namespace>")]`, so two
+  bundles of this package (an island chunk and a layout script) still meet.
+
+`@v-office/website-components` ships the React bindings (`useSearchForm`, `useSearchStore`,
+`useQuoteFlow`, `useCheckoutFlow`, `useGuestForm`, `useContactForm`, `useFavorites`, `useSdk`,
+`useLazySdk`, `useEnhance`). Any other framework needs only this:
+
+```tsx
+import { useSyncExternalStore } from "react";
+import type { Store } from "@v-office/website-headless";
+
+export function useStore<S>(store: Store<S>): S {
+  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
 }
 ```
 
-Vue: a `shallowRef` set in `subscribe`; Svelte: the store contract is the same
-two functions; a plain `<script>` island: call `getState()` in the listener.
+A plain `<script>`:
+
+```ts
+import { createSearchForm } from "@v-office/website-headless";
+
+const form = createSearchForm({ ...SEARCH_CONTRACT, guests: GUESTS });
+const stop = form.subscribe((state) => {
+  document.body.toggleAttribute("data-search-ready", state.resolved);
+});
+form.load(location.search);
+// later: stop(); form.dispose();
+```
+
+## Conventions and shared types
+
+### The rules
+
+- **Copy never enters headless.** Stores take `messages` objects (`CheckoutMessages`,
+  `ContactFormMessages`, `ValidationMessages`) and return kinds and numbers; the components' copy
+  tables satisfy those message types structurally. PMS strings (prices, reasons, labels) pass
+  through verbatim.
+- **Dates are strings.** `IsoDay` (`YYYY-MM-DD`, a local calendar day) and `IsoMonth` (`YYYY-MM`) at
+  every public boundary; `Date` only for injected clocks.
+- **Real data only.** Absent data is `undefined`, `null` or `[]`, never `0` or `""`: no fallback
+  town, no guessed count, no invented price. Money is the SDK's formatted string; no amount is
+  recomputed, and an offer's amount is carried nowhere.
+- **The SDK comes in first** (`fetchQuote(sdk, request)`), and is constructed only by `createSdk`,
+  `shareSdk` and `loadSharedSdk`.
+- **`book()`, `pay()` and the contact `submit()` are user-initiated only.** They create a real
+  reservation, start a real payment and post a real request into the PMS. No test, job or smoke step
+  calls them against a real SDK.
+- **No site names.** The source names no customer, domain or town; a ruling is an option.
+
+### One name per concept
+
+| name           | type (where)                                                     | meaning                                                                                                                                                                                             |
+| -------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `contract`     | `SearchContract` (headless `url`)                                | how the search runs on this backend; one value for the search form, the search store and the offer chips                                                                                            |
+| `guests`       | `GuestOptions` (headless `guests`)                               | stepper limits, child-age band, default adults. `limits.pets`: 0 = no dogs, 1 = a yes/no toggle, more = a stepper; every dog control follows it                                                     |
+| `whenEmpty`    | `WhenEmpty` (headless `search`)                                  | what a filter or option that matches nothing does: `"drop"`, `"disable"`, `"show"`                                                                                                                  |
+| `glyphs`       | `Glyph` vocabulary (headless `shared`); `GlyphMode` (components) | a closed list of glyph names the models emit (`GLYPHS`); components map names to icons and offer `"none" \| "default" \| "mapped"`                                                                  |
+| `voice`        | `Voice` (components)                                             | how German copy addresses the reader: `"neutral"` (default), `"du"`, `"sie"`; English ignores it. Headless carries no copy                                                                          |
+| `headingLevel` | `HeadingLevel \| "none"` (components)                            | the level of a component's own heading; a custom UI decides its own                                                                                                                                 |
+| `loadOn`       | `"near" \| "click" \| "consent"` (components)                    | when third-party map tiles may load (default `"click"`). The headless map surface loads only when told: `start: "demand"` waits for `build()`, `"near"` loads once the container nears the viewport |
+
+### Events, storage keys and URL keys
+
+These are contracts: renaming one is a major. Headless hands events to `onEvent` callbacks; the
+components dispatch them on `window`, and a custom UI dispatches the same shapes. No detail carries
+personal data.
+
+| event (constant)                        | from                                     | `detail`                                                                                                                                                                                            |
+| --------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `voffice:checkout` (`CHECKOUT_EVENT`)   | `createCheckoutFlow` `onEvent`           | `CheckoutEventDetail`: `{ type: "rate-fault", rentalId, code }` once per stay · `{ type: "booked", rentalId, bookingNumber, kind, payable }` · `{ type: "payment-started", bookingNumber, method }` |
+| `voffice:quote` (`QUOTE_EVENT`)         | `createQuoteFlow` `onEvent`              | `QuoteEventDetail`: `{ type: "rate-fault", rentalId, stayKey, code }` once per stay                                                                                                                 |
+| `voffice:contact` (`CONTACT_EVENT`)     | after `submit()` resolved `{ ok: true }` | `ContactEventDetail`: `{ type: "sent", subject }`                                                                                                                                                   |
+| `merkliste:changed` (`FAVORITES_EVENT`) | `bindFavorites` (dispatched by headless) | `FavoritesChange`: `{ id, saved }`, once per changed rental, also for another tab's change                                                                                                          |
+
+| storage                  | key                                                                                                    |
+| ------------------------ | ------------------------------------------------------------------------------------------------------ |
+| localStorage, favourites | `` `${namespace}-merkliste` `` (`favoritesStorageKey`)                                                 |
+| sessionStorage, checkout | `voffice:checkout-context` (`CHECKOUT_CONTEXT_KEY`), `voffice:booking-return` (`BOOKING_SNAPSHOT_KEY`) |
+
+The URL vocabulary is [`SEARCH_PARAMS`](#url-parameters); the sort values are
+[`SORT_URL_VALUE`](#sort).
+
+### Shared types
+
+| type                                                                        | defined in | meaning                                                                |
+| --------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------- |
+| `Locale`, `Backend`, `Stage`                                                | `sdk`      | `"de-DE" \| "en-US"`; `"v9" \| "v10"`; `"development" \| "production"` |
+| `SdkConfig`, `SdkOptions`, `SdkSetup`, `SdkMode`, `SdkSource`, `WebsiteSdk` | `sdk`      | see [Wiring a site](#wiring-a-site)                                    |
+| `IsoDay`, `IsoMonth`                                                        | `shared`   | calendar strings                                                       |
+| `Party`, `GuestLimits`, `ChildAgeRange`, `GuestCaps`, `GuestOptions`        | `guests`   | one party model for the search form, the quote and the checkout        |
+| `PriceCents`                                                                | `shared`   | how a formatted price string is trimmed (cards, pins, calendar cells)  |
+| `Glyph`                                                                     | `shared`   | the closed glyph vocabulary                                            |
+| `RichBlock`, `RichInline`                                                   | `shared`   | sanitized PMS text as data                                             |
+| `ContactLink`, `BookableFrom`                                               | `shared`   | `{ label, href }`; "not bookable online before `from`"                 |
+| `StorageLike`                                                               | `shared`   | `getItem`, `setItem`, `removeItem`                                     |
+| `WhenEmpty`                                                                 | `search`   | `"drop" \| "disable" \| "show"`                                        |
+| `RentalCounts`, `RentalDistance`, `DistanceKind`                            | `rental`   | counts and distances (absent = `undefined`)                            |
+| `CardSource`, `RentalFacts`, `RentalFactsMap`, `StayPrice`                  | `cards`    | the one card input; build-time facts per rental; a priced stay         |
+| `Stay`                                                                      | `checkout` | `{ start, end, party }`, a complete stay                               |
+
+## Search form
+
+Module `search-bar`. The search bar's state and rules: a date picker and a guest picker composed,
+the region choice, and the pairs a native GET form submits. It never calls the SDK: the bar
+navigates (the form works before hydration), and the results page refines in place.
+
+### `createSearchForm(options)`
+
+`options` is a `SearchFormOptions`; returns a `SearchForm`. Throws (at build) when `fields` lists
+`"pets"` while dogs are not offered (`guests.limits.pets` is 0).
+
+| option                                   | default                         | meaning                                                                                                                                           |
+| ---------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `backend`, `nightRangeSearch`, `aliases` | (the `SearchContract`)          | `backend` is required                                                                                                                             |
+| `fields`                                 | `["region", "dates", "guests"]` | `SearchField[]` in render order; `"pets"` renders the dog control as its own field. A field that is absent leaves its URL keys carried, not owned |
+| `regions`                                | `[]`                            | the selectable region values (labels are UI); `"region"` renders only with at least one                                                           |
+| `regionSelect`                           | `"multi"`                       | `"multi"` (OR) or `"single"` (one region or all)                                                                                                  |
+| `dates`                                  | `{}`                            | the date picker's options (`createDateSearch`, without `backend` and `nightRangeSearch`)                                                          |
+| `guests`                                 | `{}`                            | `GuestSearchOptions` (`GuestOptions` plus `showDefault`)                                                                                          |
+| `childAges`                              | `"required"`                    | `"required"`: a child without an age stops the submit; `"optional"` submits the ages that exist                                                   |
+| `preset`                                 | none                            | a landing page's starting search (a query string): its owned keys seed the pickers only when the URL owns none, its other pairs ride along        |
+| `now`                                    | `() => new Date()`              | the clock                                                                                                                                         |
+
+`SearchFormState`: `fields` (the ones that render), `dates` (`DateSearchState`), `guests`
+(`GuestSearchState`), `regions`, `carried` (pairs the bar does not own: sort, filters, property,
+campaign, a site's own keys), `resolved` (false until `load()` ran: show skeletons, disable the
+submit), `issue` (`SearchFormIssue`: `{ kind: "agesMissing" }` after a refused submit, cleared by
+the next change).
+
+| action                                                                 | what it does                                                                                                                                                    |
+| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dates`, `guests`                                                      | the composed `DateSearch` and `GuestSearch`; their actions drive the panels                                                                                     |
+| `load(search)`                                                         | read the URL (and the preset) into the pickers                                                                                                                  |
+| `toggleRegion(value)`, `selectRegion(value \| null)`, `clearRegions()` | the region choice; values outside `regions` are ignored                                                                                                         |
+| `pairs()`                                                              | `writeSearch(pickers) + carried`: the GET form's hidden inputs                                                                                                  |
+| `submit(current?)`                                                     | `{ ok: true, pairs }` or `{ ok: false, issue }`. Pass `location.search`: the carried pairs are re-read from it, so filters and sort changed in place ride along |
+| `reset()`                                                              | pickers and regions back to nothing chosen; carried pairs stay                                                                                                  |
+| `update(options)`, `dispose()`                                         | change options (not the backend); stop listening                                                                                                                |
+
+```ts
+import { createSearchForm } from "@v-office/website-headless";
+
+const form = createSearchForm({ ...SEARCH_CONTRACT, regions: ["Nord", "Süd"], guests: GUESTS });
+form.load(location.search);
+
+const element = document.querySelector("form[data-search]");
+element?.addEventListener("submit", (event) => {
+  event.preventDefault();
+  const result = form.submit(location.search);
+  if (!result.ok) return; // state.issue: open the guest panel and ask for the ages
+  const query = new URLSearchParams(result.pairs.map(([key, value]) => [key, value]));
+  location.assign(`/suchen?${query.toString()}`);
+});
+```
+
+### `createDateSearch(options)`
+
+The period a guest is picking (`DateSearchOptions` → `DateSearch`). The calendar always shows the
+guest's own stay; only what a submit sends widens (± steps). Which controls exist comes from the
+SDK's capability helpers for the backend.
+
+| option             | default                        | meaning                                                                                                                                   |
+| ------------------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `backend`          | required                       | decides the flexible tab and how a ± step is spelled                                                                                      |
+| `nightRangeSearch` | `true`                         | whether the backend prices a `minNights`/`maxNights` window                                                                               |
+| `flexSteps`        | `[0, 1, 2, 3, 7, 14]`          | ± chips in days; `[]` or `[0]` = no chip row. On v10 always, on v9 only with `nightRangeSearch`                                           |
+| `flexibleStays`    | `["weekend", "week", "month"]` | `[]` removes the flexible tab (v10 only)                                                                                                  |
+| `nightRangeRow`    | `false`                        | render the Min./Max. nights row (beside exact dates and a window of at least 2 nights)                                                    |
+| `minStayNights`    | `1`                            | closer departure days are disabled                                                                                                        |
+| `bookable`         | none                           | `BookableFrom`: `from` floors the calendar, the month strip and ± windows; `deferred` is true while today is before `noticeUntil ?? from` |
+| `now`              | `() => new Date()`             | read on every action, so a bar left open past midnight moves its floor                                                                    |
+
+`DateSearchState`: `mode` (`DateMode`: `"dates" | "flexible"`), `from`, `to`, `flexDays`,
+`nightRange`, `stay` (`FlexibleStay | null`), `months`, `windowNights`, `controls` (`DateControls`:
+`flexibleTab`, `flexSteps`, `nightRangeRow`: what to render now), `floor`, `deferred`,
+`monthOptions` (twelve months from the floor's month) and `period` (`SearchPeriod | null`, what a
+submit sends).
+
+Actions: `pick(day)` (first click sets `from`, second `to`, a click on a finished stay starts a new
+one), `isDisabled(day)`, `setMode`, `setFlexDays`, `setMinNights`, `setMaxNights` (moving one bound
+past the other pushes it along), `setStay`, `toggleMonth`, `load(period)` (a period the controls
+cannot show loads as empty), `reset()`, `update(options)`.
+
+### Period labels
+
+- `describePeriod(period, locale, today?)` → `PeriodLabel` (`dates`, `flexDays`, `nights`, `stay`,
+  `months`): the summary parts of a `SearchPeriod`, a partial pick (`{ kind: "partial", from, to }`)
+  or `null`. No copy words: the UI adds "± {days} Tage" and the like.
+- `formatStayRange(from, to, locale, today?)` → `"4. – 11. Sept."`,
+  `"30. Dez. 2026 – 3. Jan. 2027"`: the month once, the year only when it is not the current one,
+  months through `Intl` (the result cards use the same).
+
+### Rental jump
+
+A rental-name search box over the site's static index (the live search has no free-text key, so this
+is catalogue matching, never a filter).
+
+- `rentalIndexEntries(rentals, href, { code? })` (build) → `RentalIndexEntry[]` (`id`, `name`,
+  `href`, `code?`, `place?` = the town). `href` is the site's own detail URL.
+- `loadRentalIndex(url)` (browser) fetches the JSON once per URL per page; a failure is not cached.
+  Rows without a string `id`, `name` and `href` are dropped.
+- `matchRentals(entries, query, options?)` (`RentalMatchOptions`: `limit` 8, `minChars` 2) →
+  `RentalMatch` (`hits`, `total`). Every query word must occur in the name, place or code, in both
+  umlaut spellings ("duene" and "dune" find "Düne"); ranked code exact, name exact, name prefix,
+  word start, contains.
+- `foldSearchText(raw)`: lowercase, ä→ae ö→oe ü→ue ß→ss, other diacritics stripped.
+
+## URL parameters
+
+Module `url`. The search funnel's URL vocabulary and its codec: written canonically, read leniently
+(the SDK's aliases, the legacy `pets` flag and a site's own aliases are read, never written).
+
+### `SEARCH_PARAMS`
+
+Every key of the funnel's wire format (`SearchParamKeys`). Links live in bookmarks, indexes and
+mails: renaming one is a major.
+
+| key                                            | meaning                                                                                                                      |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `start`, `end`                                 | arrival and departure (`YYYY-MM-DD`); on a ± or night-range search the window's bounds                                       |
+| `dates`, `nights`                              | v10 ± window `DD-MM-YYYY,DD-MM-YYYY` and its stay length                                                                     |
+| `month`, `weekend`                             | v10 flexible months (`MM-YYYY`, repeatable) and the weekend flag                                                             |
+| `minNights`, `maxNights`                       | the night range inside a `start`/`end` window                                                                                |
+| `flex`                                         | the ± step the guest chose; UI only, never sent to the SDK                                                                   |
+| `adults`, `children`, `childrenAges`, `babies` | the party; `childrenAges` is one comma list aligned to `children`                                                            |
+| `petsCount`, `pets`                            | dogs: search pages write `petsCount`, rental and checkout pages `pets` (an integer); old search links carry `pets` as a flag |
+| `region`, `property`                           | scopes (`region` repeatable, OR-combined, applied in the browser)                                                            |
+| `sort`, `campaign`                             | the results ordering; an offer campaign scope                                                                                |
+| `policy`, `kind`, `return`, `offer`            | the chosen rate (rental → checkout), a booking kind, the payment-return marker, an offer label carried to the rental page    |
+
+### The codec
+
+- `SearchContract`: `{ backend, nightRangeSearch?, aliases? }`. `nightRangeSearch` (default `true`):
+  set `false` on a v9 hub that answers the night pair unpriced; no control writes it, nothing reads
+  or sends it
+- `SearchParamAliases`: legacy keys read as a canonical one (`start`, `end`, `region`, `adults`,
+  `children`, `childrenAges`, `babies`, `petsCount`). `from`/`till`/`nights_min`/`nights_max` are
+  always read
+- `readSearch(search, contract, today?)`: query string → `SearchQuery` (`period`, `party`,
+  `regions`, `carried`). Tolerant: anything unreadable is "not stated". A v9 link with v10 flexible
+  keys reads as no period; flexible months already past are dropped
+- `writeSearch(query, contract, options?)`: `SearchQuery` → `QueryPair[]` (`WriteSearchOptions`:
+  `floor`, `defaultAdults`) spelled for the backend, in the order period, party, regions, carried.
+  Dogs as `petsCount`; a written period always travels with adults (`defaultAdults`, default 2: a
+  dated v10 search without occupancy answers nothing). `floor` (default today) clamps the lower end
+  of a ± window
+- `searchHref(action, query, contract, options?)`: `action` (may carry a `#fragment`) plus
+  `writeSearch`
+- `readParty(params, aliases?)`: the party from any funnel URL: `petsCount` wins over `pets`,
+  `pets=true` reads as 1, ages aligned to `children`; `null` without any party key
+- `partyPairs(party, petsKey)`: the party as pairs (`petsKey` `"petsCount"` or `"pets"`); zero
+  counts omitted
+
+`SearchPeriod` is a period by meaning; `writeSearch` spells it per backend:
+
+| `kind`       | fields                                                             | URL                                                                                                                           |
+| ------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `exact`      | `start`, `end`                                                     | `start` + `end`                                                                                                               |
+| `plusMinus`  | `start`, `end` (the guest's stay), `days`                          | v10: `dates` + `nights` + `flex`; v9: the widened `start`/`end` + `minNights = maxNights` + `flex` (needs `nightRangeSearch`) |
+| `nightRange` | `start`, `end`, `minNights`, `maxNights`                           | `start` + `end` + the pair (the window alone where the pair is not priced)                                                    |
+| `flexible`   | `months` (`IsoMonth[]`), `stay` (`"weekend" \| "week" \| "month"`) | v10 only: repeated `month` + `weekend=1`, `nights=7`, or the days of the earliest month                                       |
+
+```ts
+import { readSearch, searchHref, type SearchContract } from "@v-office/website-headless";
+
+const contract: SearchContract = {
+  backend: "v9",
+  aliases: { start: ["checkin"], end: ["checkout"] },
+};
+const query = readSearch(
+  "?checkin=2027-05-10&checkout=2027-05-17&adults=2&sort=preis-auf",
+  contract,
+);
+// query.period: { kind: "exact", start: "2027-05-10", end: "2027-05-17" }; query.carried: [["sort", "preis-auf"]]
+const href = searchHref("/suchen", { ...query, regions: ["Nord"] }, contract);
+```
+
+## Guests
+
+Module `guests`. One party model and its rules, shared by the search form, the quote and the
+checkout. Babies and dogs never count against a person cap. A type whose limit is 0 is "not
+offered": it renders no control and keeps whatever value it arrived with ("hidden means not offered,
+never not honoured").
+
+- `Party`: `{ adults, children, childrenAges: (number | null)[], babies, pets }`. `adults` 0 = none
+  chosen yet; an age is `null` until chosen
+- `GuestKind`: `"adults" | "children" | "babies" | "pets"`
+- `GuestLimits`, `DEFAULT_GUEST_LIMITS`: stepper maxima; defaults adults 16, children 6, babies 5,
+  pets 4. 0 = not offered; pets 1 = a yes/no choice
+- `ChildAgeRange`, `DEFAULT_CHILD_AGE`: the selectable child ages, default 2–17 (younger is a baby)
+- `GuestOptions`: `{ limits?: Partial<GuestLimits>, childAge?, defaultAdults? }` (default adults 2):
+  the `GUESTS` constant
+- `GuestCaps`: a rental's caps: `maxPersons`, `maxAdults` (availability) beat `maxGuests`
+  (catalogue, used where availability states none: v9 before SDK 2.28) beat the limits; a stated cap
+  above the limit wins (a 20-person house). `childrenAllowed: false` (v9 availability) offers no
+  children or babies; `maxPets` (v9 availability) caps dogs, `0` offers none; `petsAllowed: false`: no
+  dog can be added. A count that arrived by link and one of these rules out can be lowered and is
+  still sent
+- `guestBounds(party, { limits?, caps? })`: `GuestBounds`: per kind a `GuestBound` (`offered`,
+  `min`, `max`) (adults min 1). Adults win a shared person cap: children get what the adults leave.
+  Compute the bounds from the party before an edit
+- `clampParty(party, bounds)`: offered types clamped; a not-offered type keeps its value; `adults` 0
+  stays 0; ages follow the children count
+- `agesComplete(party)`: every child has an age (the age prices the stay)
+- `occupancyOf(party)`: the SDK's `QuoteOccupancy`; unchosen ages left out
+- `stayKeyOf({ start, end, party })`: dates and party as one comparable string (supersession in the
+  quote and checkout)
+
+### `createGuestSearch(options?)`
+
+The party a guest is building, as a store (the search form composes one; a custom guest UI may use
+it alone). Options: `GuestOptions` plus `showDefault` (default `false`: start at `defaultAdults`
+when the URL states no party) and `caps`.
+
+State: `party`, `shownAdults` (chosen, or `defaultAdults`: what the stepper and the summary show and
+a submit sends), `hasSelection`, `agesComplete` (always true while children are not offered),
+`bounds`, `ageOptions`, `occupancy` (what a submit sends). Actions: `set(kind, count)`,
+`setAge(index, age | null)`, `load(party | null)` (ages outside the band become unchosen, so the
+guest is asked again), `reset()`, `update(options)`.
+
+## Search store and live search
+
+Module `search`. The page's one live search: walk, scopes, browser filters, viewport, sort, campaign
+and outcome. Grid, map, count, chips and filter islands read the same store, because the SDK queues
+searches at 1 request per second.
+
+### `createSearchStore(source, options)`
+
+`options` is a `SearchStoreOptions`; returns a `SearchStore` (`Store<SearchState>` plus
+`SearchActions` and `dispose()`). **It starts searching when created.** It reads and writes the URL
+only through the injected `history` port and never creates or disposes the SDK.
+
+| option                                   | default                   | meaning                                                                                                               |
+| ---------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `backend`, `nightRangeSearch`, `aliases` | (the `SearchContract`)    | `backend` is required                                                                                                 |
+| `rentalHref`                             | required                  | a `RouteTemplate` with `{slug}` or `{id}` for rentals the facts give no `href`                                        |
+| `locale`                                 | required                  | the language of the PMS strings and the stay labels                                                                   |
+| `history`                                | required                  | `HistoryPort`: `read()`, `write(search, "push" \| "replace")`, `subscribe(onChange)` (components: `browserHistory()`) |
+| `seed`                                   | required                  | the random-sort seed, drawn once per page view                                                                        |
+| `facts`                                  | none                      | `RentalFactsMap`: build-time facts that fill what the live projection lacks and answer the browser filters            |
+| `filters`                                | none                      | `ResolvedFilters`; without it only period and occupancy reach the SDK                                                 |
+| `scope`                                  | none                      | `SearchScope` (below)                                                                                                 |
+| `favorites`                              | none                      | a `FavoritesPort` (`ids()` + `subscribe`); required for `scope.favorites`. `Favorites` satisfies it                   |
+| `campaignOf`                             | `campaignGroup`           | offer label → campaign group                                                                                          |
+| `preset`                                 | none                      | applied (`replace`) when the URL carries no search of its own                                                         |
+| `requireFacts`                           | `false`                   | drop rentals the build has no facts for (no detail page was built)                                                    |
+| `reveal`                                 | `"complete"`              | `"first-page"`: the first page shows at once; the browser sort, the outcome and the count wait for the rest           |
+| `sdkMode`                                | `"default"`               | the mode the SDK was created in                                                                                       |
+| `leaveMs`                                | `FAVORITE_LEAVE_MS` (280) | the favourites page's removal window; 0 = immediate (pass 0 under reduced motion)                                     |
+| `now`                                    | `() => new Date()`        | the clock (also `sanitizeSearch`'s today)                                                                             |
+
+`SearchScope` narrows the one result set, applied in this order: `ids` (a fixed set from the build:
+a theme, a property, a landing page) → `favorites: true` (the Merkliste; on v10 restricted
+server-side) → `offers` (discounted results only; `labels` narrows to exact PMS labels, `campaign`
+to a whole campaign, `window: OffersWindowSpec` makes the page search its offers window when the URL
+carries no period). Then the browser filters and `requireFacts`, the URL's `?campaign=`, the map
+viewport and the sort.
+
+**When a request runs.** On create the store sanitizes the URL (a past or unreadable stay is dropped
+with `replace`), applies `preset` where the URL has no search, and the offers window where it has no
+period. A new live search runs only when the SDK-facing part changes (period, occupancy, SDK filter
+keys, an id restriction, a server sort while the set is incomplete). Facts filters, scopes, the
+campaign and a browser sort re-derive from the loaded set without a request. A walk reads every page
+(sequentially, capped at 100 pages); a v9 ± search also asks the guest's own dates exactly and
+prefers those answers.
+
+`SearchState`:
+
+- `status`: `SearchStatus`: `"loading"` until the first answer, `"ready"`, or `"error"` only when
+  nothing loaded
+- `complete`: every page is in (false while a first-page reveal loads, and after a later page
+  failed: what loaded stays)
+- `search`, `shape`: the current query (sanitized, no `?`) and its `QueryShape`
+- `scope`: `SearchScopeKind`: `"search"`, `"favorites"`, `"offers"`, `"ids"`
+- `matched`: after scopes, filters and the campaign, before the viewport: what the map plots
+- `items`, `count`: after the viewport and the sort: what the list renders, and how many (leaving
+  favourites excluded from the count)
+- `allAlternatives`: every result is an alternative on an exact search (show the notice); waits for
+  `complete`
+- `sort`, `sortOptions`: the `SortKey` in the URL; every key with whether it can be chosen now
+- `filters`, `activeFilters`, `filterCounts`: the resolved filters; the applied ones (chips, hidden
+  included, led by a `?property=` or `?region=` scope the curation has no facet for: see
+  [Filters](#filters)); live counts over the listed set (`key` for a flag, `key=value` for a facet
+  value)
+- `offerLabels`, `campaign`: distinct PMS offer labels of the scoped results (before `?campaign=`
+  narrows); the campaign in scope
+- `outcome`: `SearchOutcome` (error or empty with ways out), or null while results show or the walk
+  has not settled
+- `unusedFilterKeys`: keys the backend reported as having had no effect
+- `highlighted`, `reloading`, `viewportActive`, `leaving`: the hovered card; the map's 220 ms
+  re-settle pulse; a viewport filter is active; favourites un-hearted a moment ago (still in
+  `items`, animating out)
+
+| action                                                              | what it does                                                                                                   |
+| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `setSearch(search, mode = "push")`                                  | change the query                                                                                               |
+| `setSort(key)`                                                      | order in place (`replace`)                                                                                     |
+| `applyFilters(selection)`, `removeFilter(filter)`, `clearFilters()` | the filter panel, a chip, "remove all" (push; hidden filters and implicit scopes included in `clearFilters`)   |
+| `setViewport(ids \| null)`, `setReloading(on)`                      | the map's in-view ids (results without coordinates always stay) and its pulse (the map controller calls these) |
+| `releaseRegionScope()`                                              | drop `?region=` (push) so neighbouring results come back                                                       |
+| `setCampaign(group \| null)`                                        | the campaign chip (`replace`); a `?campaign=` the complete results cannot honour clears itself                 |
+| `setHighlighted(id \| null)`, `retry()`                             | the hovered card; re-run after an error                                                                        |
+| `dispose()`                                                         | stop listening to the URL and the Merkliste, drop a running walk (the SDK stays)                               |
+
+```ts
+import {
+  acquireSearchStore,
+  createSearchStore,
+  loadRentalFacts,
+  shareSdk,
+  type HistoryPort,
+} from "@v-office/website-headless";
+
+const history: HistoryPort = {
+  read: () => location.search,
+  write: (search, mode) => {
+    const url = `${location.pathname}${search ? `?${search}` : ""}${location.hash}`;
+    if (mode === "push") window.history.pushState(null, "", url);
+    else window.history.replaceState(window.history.state, "", url);
+  },
+  subscribe: (onChange) => {
+    window.addEventListener("popstate", onChange);
+    return () => window.removeEventListener("popstate", onChange);
+  },
+};
+
+const shared = shareSdk(SDK);
+const facts = await loadRentalFacts("/rental-facts.json");
+const { store, release } = acquireSearchStore("results", () =>
+  createSearchStore(shared.sdk, {
+    ...SEARCH_CONTRACT,
+    locale: "de-DE",
+    rentalHref: "/unterkuenfte/{slug}",
+    history,
+    facts,
+    seed: Math.floor(Math.random() * 2 ** 31),
+  }),
+);
+const stop = store.subscribe((state) => {
+  if (state.status === "ready") console.log(`${state.count} results`);
+});
+// teardown: stop(); release(); shared.release();
+```
+
+### Page-shared stores
+
+- `acquireSearchStore(key, create)` → `SearchStoreClaim` (`{ store, release() }`): the store under
+  `key`, created by the first caller. Every island of the page (grid, map, count, chips) claims the
+  same key; the last release disposes it.
+- `connectSearchStore(key, onStore)` → detach: follow a store that may appear later (a satellite
+  island hydrating before the results); `onStore(null)` when it is released.
+
+### Result items
+
+`SearchResultItem` is one rental in the result list (grid, map and count share it): `id`, `name`,
+`location` (`""` when the feed states none), `href` (the site's page plus the handover query),
+`hrefWithoutDates`, `images` (`CardImage[]`, WebP where served), `counts`, `highlights`,
+`rentalType`, `price` (`StayPrice | null`), `stay` (`StayWindow | null`: the priced stay when it is
+not simply the searched dates), `alternative`, `periods` (`AlternativePeriod[]`), `propertyId`,
+`coords`, `rating` (from the facts only).
+
+- `runLiveSearch(sdk, search, options)`: one request with the caller's SDK → `SearchPage` (`items`,
+  `shape`, `cursor`, `hasNextPage`, `totalCount`, `unusedFilterKeys`). `LiveSearchOptions`: the
+  contract, `rentalHref`, `locale`, `facts`, `filters`, `sort` (default `"recommended"`), `cursor`,
+  `rentalIdsIn` (v10). The store does not use it; it is for a one-off request
+- `catalogueResultItem(rental, options)`: a catalogue rental as a result item for a server-rendered
+  listing (no price, no stay, a link without booking context)
+- `compareUndatedSearchOrder(a, b)`: the order an undated search returns, as far as a build can
+  reproduce it (numeric id ascending on v9, code-unit order on v10), so the island's swap moves
+  nothing
+- `resultCardSource(item, facts?)`: the `CardSource` of one result: live fields from the item,
+  catalogue fields from the facts
+- `ResultLinkOptions`: `{ rentalHref, facts?, locale }`
+
+### Queries and links
+
+- `toSdkQuery(search, options)`: URL query → `SdkSearchQuery` (`query`, `sort?`, `withheld`). An
+  allowlist: the period keys this backend executes, occupancy, and the resolved filters' SDK keys;
+  every other key stays in the URL. `SdkQueryOptions`: the contract, `sort`, `sdkFilterKeys`,
+  `retiredKeys`
+- `queryShape(search, contract)`: `QueryShape`: `exactDates`, `priced` (a period and at least one
+  adult: totals arrive, price sort possible), `dated`, `nights`, `window`, `ownStay` (the v9 ± stay
+  asked as a second question), `hasSearch`
+- `handoverQuery(search, options?)`: `ResultHandoverOptions` (`stay`, `offerLabels`). The `?…` a
+  result link carries: the period (or the given stay), the party (dogs as `pets`), at most four
+  `offer=` labels and only with a period
+- `externalSearchHref(link, search, contract)`: a link to a partner's search from the current one
+  (`ExternalSearchLink`: `base`, `params` (partner name → `ExternalSearchSource`), `dateFormat`
+  `"iso"`, `"d.m.yyyy"` or `"dd.mm.yyyy"`). Values without data are omitted. Throws on a `base` that
+  is not an absolute URL
+- `sanitizeSearch(search, today)`: `SanitizedSearch` (`search`, `dropped`): an unsearchable stay
+  (past, reversed, unreadable, half a pair) dropped with its night range and `flex`, instead of an
+  error page
+- `resultsQueryFlagScript()`: inline `<head>` script source that sets `html[data-results-query]`
+  before first paint when the URL carries a real search, so a prerendered listing never flashes
+  under a search it does not answer
+
+### Sort
+
+| `SortKey`     | URL value (`SORT_URL_VALUE`) | runs                                                                                    |
+| ------------- | ---------------------------- | --------------------------------------------------------------------------------------- |
+| `recommended` | `empfohlen`                  | the backend's order; no sort sent                                                       |
+| `price-asc`   | `preis-auf`                  | priced queries only; sent to the SDK and re-applied in the browser over the merged list |
+| `price-desc`  | `preis-ab`                   | as `price-asc`                                                                          |
+| `rating`      | `bewertung`                  | browser only, missing values last                                                       |
+| `area-desc`   | `groesse`                    | browser only                                                                            |
+| `area-asc`    | `groesse-auf`                | browser only                                                                            |
+| `guests`      | `gaeste`                     | browser only                                                                            |
+| `bedrooms`    | `schlafzimmer`               | browser only                                                                            |
+| `random`      | `zufall`                     | browser only, seeded per page view                                                      |
+
+- `DEFAULT_SORT_OPTIONS`: `["recommended", "price-asc", "price-desc"]`, the short list for a site
+  that does not choose its own. Any known value in the URL is honoured even when the control does
+  not offer it.
+- `sortFromSearch(search)` → `SortKey` (`"recommended"` when absent or unknown).
+- `toSdkSort(key, shape)` → the SDK ordering, or `undefined` (price needs a priced query).
+- `sortResults(items, key, seed)`: stable, missing values last, never as 0.
+- `SortOptionState`: `{ key, available, reason?: "needs-price" | "needs-data" }`.
+
+### Filters
+
+The package ships no curation: which keys, groups and order a portfolio needs is measured per site.
+Every applied filter stays visible and removable; "hidden" means not offered as a control, never not
+honoured.
+
+`?region=` (the search bar's region field) and `?property=` (an Anlage link) narrow the results
+even where the curation has no facet for them. The search store then lists them first in
+`state.activeFilters` as facet chips with `scope: "region" | "property"` (`ImplicitScope`), an empty
+`label` (the copy words them, "Region: {value}", "Anlage: {value}") and the URL value verbatim as
+`value`; `removeFilter` and `clearFilters` remove them, and an empty result names them as the
+`"filters"` cause. A curated (hidden) facet for the key replaces the implicit chip with its own label
+and option labels, which is how a property chip shows the property's name instead of its id.
+
+A `FilterSpec` is `{ groups: FilterGroupSpec[], retired?: string[] }`; a group is
+`{ id, title, entries, hidden? }`; an entry (`FilterEntry`) is one of:
+
+| `kind`    | answered by                                                       | fields                                                          |
+| --------- | ----------------------------------------------------------------- | --------------------------------------------------------------- |
+| `sdk`     | the backend (`getFilters`: a boolean, or an int minimum)          | `key`, `label?` (overrides the SDK's), `max?` (stepper maximum) |
+| `flag`    | the browser, from `facts.flags[key]`                              | `key`, `label`                                                  |
+| `minimum` | the browser, from `facts.counts[field]` or `facts.numbers[field]` | `key`, `label`, `field`, `min?` (1), `max`                      |
+| `facet`   | the browser, OR within, from `facts.facets[key]`                  | `key`, `label`, `options: FacetOption[]`, `multiple?` (true)    |
+| `pets`    | occupancy `petsCount`                                             | the dogs pill, placed where the entry sits                      |
+
+Every entry and group may be `hidden`. `retired` keys are still executed by the backend but match
+nothing here: they are stripped from every query, so an old link cannot empty the page invisibly.
+
+- `resolveFilters(sdkFilters, spec, options?)`: the curation resolved against
+  `sdk.static.filter.getFilters` (its output passes as it is) → `ResolvedFilters` (`groups`, `defs`,
+  `sdkKeys`, `retired`), serializable. An SDK key the SDK no longer returns self-hides; option and
+  string filters in an `sdk` entry are skipped; int bounds default to 1..8.
+  `ResolveFiltersOptions`: `counts`, `total` (from `measureFilters`), `whenEmpty` (default
+  `"drop"`), `whenUniversal` (default `"drop"`: a filter matching everything does not filter)
+- `measureFilters(sdk, keys, { locale, baseline? })`: build time, opt-in: hits per boolean key
+  against a baseline (default `"adults=1"`), one request per key, sequential → `FilterMeasurement`
+  (`total`, `counts`). A count the backend does not state is left out
+- `facetOptions(facts, key, options?)`: facet options from the build's facts with their counts
+  (`FacetOptionsOptions`): `order` `"label"` (default), `"count-desc"` or an explicit list;
+  `labels`; `locale` (collation, default `"de-DE"`)
+- `readSelection(search, filters)`, `writeSelection(search, filters, selection)`: the URL round trip
+  of a `FilterSelection` (`booleans`, `minimums`, `facets`, `pets`). Writing rewrites visible defs
+  only, keeps hidden ones, writes dogs as `petsCount` and never lowers the URL's dog count
+- `activeFilters(search, filters)`: the applied filters of the curation as `ActiveFilter[]` (chips;
+  `id` is `key` or `key=value`; the copy words them). The store's `state.activeFilters` adds the
+  implicit scopes (above)
+- `withoutFilter(search, filter)`, `withoutFilters(search, filters)`: the query without one chip, or
+  without every filter (dates, party and scopes kept)
+- `minimumSteps(def, value)`: a minimum stepper's `{ down, up }`: the first step up lands on the
+  floor, the step down from the floor returns to "any"
+- `quickFilterDefs(filters, keys)`: the quick strip's defs in `keys` order (visible booleans only)
+- `FilterDef`, `SdkFilterDefinition`, `FacetOption`, `WhenEmpty`, `ImplicitScope`: the resolved def
+  union (`boolean`, `minimum`, `facet`, `pets`), the minimal shape read off `getFilters` (every kind
+  it returns), one facet value, the zero-match decision, `"region" | "property"`
+
+```ts
+import { resolveFilters, type FilterSpec } from "@v-office/website-headless";
+
+const FILTER_SPEC: FilterSpec = {
+  groups: [
+    {
+      id: "features",
+      title: "Ausstattung",
+      entries: [
+        { kind: "sdk", key: "sauna" },
+        { kind: "flag", key: "seaView", label: "Meerblick" },
+        { kind: "pets" },
+      ],
+    },
+    {
+      id: "size",
+      title: "Größe",
+      entries: [
+        { kind: "minimum", key: "bedrooms", label: "Schlafzimmer", field: "bedrooms", max: 6 },
+      ],
+    },
+  ],
+};
+// Build time, over the loaders' one SDK (see "Which SDK instance").
+const filters = resolveFilters(
+  await sdk.static.filter.getFilters({ locale: "de-DE" }),
+  FILTER_SPEC,
+);
+```
+
+### Outcome
+
+`describeOutcome(input: OutcomeInput)` → `SearchOutcome | null` (null when there are results). The
+store computes it; a custom UI reads `state.outcome`.
+
+- `{ kind: "error" }`, or `{ kind: "empty", scope, causes, searched, relaxations }`.
+- `scope`: `"search"`, `"favorites-none-saved"`, `"favorites-none-match"`, `"offers"` (nothing
+  reduced in this period, normal much of the year), `"ids"`.
+- `causes` (`EmptyCause[]`, most actionable first): `"filters"`, `"pets"`, `"dates"`, `"party"`
+  (more than 2 guests). An empty Merkliste has none.
+- `relaxations` (`Relaxation[]`): one concrete query per cause, guaranteed to differ from the
+  current one: `"without-filters"`, `"without-pets"`, `"without-dates"` (removes every period key),
+  `"fewer-guests"` (2 adults).
+- `searched` (`SearchedParts`): `guests`, `dated`, `pets`, `filters`.
+
+### The paged walker
+
+Module `sdk`. Every live-search walk (the store, `fetchRentalFlags`, `resolveSearchGroups`,
+`findOfferWindows`) pages through one walker, so the paging rules cannot drift.
+
+- `SEARCH_PAGE_SIZE` = 100 (below the v9 hub's per-request price cap; constant within a walk).
+- `fetchSearchPage(sdk, request, cursor?)` → one `RawSearchPage`; a failure is logged as
+  `"search.search"` and rethrown.
+- `walkSearchPages(sdk, request, options?)` (`WalkOptions`: `maxPages`, `signal`): an async
+  generator over every page, strictly sequential; its return value is `WalkSummary` (`pages`,
+  `truncated`). No cap by default: a walk is never silently cut. Throws `RangeError` for
+  `maxPages < 1`.
+- `SearchPageRequest`: `query` (exactly as the SDK takes it), `locale`, `sort?`, `rentalIdsIn?` (v10
+  only; a v9 request carrying it throws), `sdkMode?`. A field sort on v9 throws.
+
+## Offers
+
+Module `search`. Offers pages: the window an offers page searches, the campaign grouping, the
+build-time sweep for each campaign's nearest window, and the chip row. A promotion belongs to a
+rental × window pair: there is no offer filter key, and a discount is revealed only by pricing a
+window, so every window number is a portfolio fact the site measured.
+
+- `OffersWindowSpec`: `startOffsetDays` and `nights` (required), `flexDays` (14), `adults` (2),
+  `earliestArrivalOffset` (1), `seasonStart` (an absolute first arrival, from `findCampaignStart`)
+- `offersWindowQuery(spec, today)`: the query an offers page searches today: `start`/`end` +
+  `minNights = maxNights` + `flex` + `adults`, the ± shape both backends execute. Throws on a spec
+  no window can come from
+- `findOfferWindows(sdk, options)`: `FindOfferWindowsOptions`. Build time, opt-in: one walk per
+  offset (default `[0, 90, 180, 270]`, `spanDays` 30, `maxPages` 8 per offset), sequential →
+  `OfferWindow[]`, one per campaign at its nearest offset. `nights` and `locale` are required.
+  Cached per process and arguments; `[]` when nothing is discounted
+- `findCampaignStart(sdk, options)`: `FindCampaignStartOptions`. Build time: the first arrival day
+  (an exact stay of `nights`, default 7, probed weekly up to `horizonDays`, default 180) on which
+  `campaign` is offered, or null. Feeds `seasonStart`
+- `offerWindowHref(action, window, contract)`: the search an `OfferWindow` links to (its ± window,
+  its party, `campaign=`)
+- `campaignGroup(label)`: the default `CampaignOf`: strips a trailing percentage only ("Frühbucher
+  10 %" → "Frühbucher"), so it fails by not grouping, never by merging two campaigns
+- `campaignChips(input)`: `CampaignChipsInput` (`state`, `windows`, `action`, `contract`, `locale`)
+  → the chip row (`CampaignChip[]`): `toggle` chips for campaigns at home in the current window,
+  `link` chips (with `href` and the `period` text) for campaigns at home elsewhere. No counts
+
+The search store takes the page's scope as `scope: { offers: { campaign?, labels?, window? } }`.
+
+## Results map
+
+Module `map`. The results map's pure rules and its behaviour as a store over the search store. The
+MapLibre engines that draw it are in [`./enhance`](#map-engines).
+
+### `createResultsMapController(source, options?)`
+
+`options` is a `ResultsMapOptions`; returns a `ResultsMapController`. `source` is the search store
+(`MapResultsSource`: `getState`, `subscribe`, `setViewport`, `setReloading`, `releaseRegionScope`).
+The map never writes into card markup: it tells the store which ids are in view and the list
+follows. Rules, in order:
+
+1. The surface that drives the list is the open fullscreen surface, else the inline one.
+2. While `listFollowsMap` is false, before the guest moved the map, or while the driving surface has
+   no size: no viewport filter (every card shows).
+3. A guest move whose in-view set differs from the last: the 220 ms pulse (`RELOAD_FLASH_MS`), then
+   the new set.
+4. New points before a guest move refit the camera (`frameVersion + 1`); after one the camera stays.
+5. The open popup closes when its rental leaves the points.
+6. `regionScope: "release-on-move"`: the first guest move drops the `?region=` scope.
+
+| option           | default                      | meaning                                                                                       |
+| ---------------- | ---------------------------- | --------------------------------------------------------------------------------------------- |
+| `listFollowsMap` | `true`                       | the list shows only the results in the visible area once the guest moved                      |
+| `regionScope`    | `"keep"`                     | `"release-on-move"`                                                                           |
+| `sameSpot`       | `"fan"`                      | `SameSpotMode` (below)                                                                        |
+| `fit`            | `DEFAULT_FIT` (`DefaultFit`) | `FitOptions`: `padding` 56, `maxZoom` 12, `excludeOutliers` true                              |
+| `pins`           | `{}`                         | `PinLabelOptions`: `price` `"total"` or `"hidden"` (every pin a dot), `cents` (`"hide-zero"`) |
+
+`ResultsMapState`: `status` (`"waiting"` while the search loads: fetch no tiles, `"empty"`,
+`"ready"`), `points`, `priced`, `layout`, `frame`, `frameVersion`, `openId`, `expandedGroup`,
+`guestMoved`. Actions: `report(surface, view)` (`ResultsMapSurface` `"inline"` or `"fullscreen"`,
+`MapViewReport` `{ bounds, byGuest }`) after every `moveend` and size change (`bounds: null` for a
+surface without size), `setPinWidth(px)`, `openPin(id)`, `closePopup()`, `toggleGroup(key | null)`,
+`dispose()`.
+
+### The pure rules
+
+- `mapPoints(items, options?)`: mappable results in result order → `MapPoint[]` (`id`, `at: LngLat`,
+  `label` or null for a dot, `sortValue`); items without coordinates are skipped
+- `hasMapPoints(items)`: at least one result can be pinned (the map's and the mobile map pill's
+  condition)
+- `frameFor(points, options?)`: the first frame (`MapBounds`) or null. Outliers (more than 10× the
+  median distance, from 4 points) do not aim the camera but stay pinned
+- `idsInView(points, bounds)`: the ids inside the bounds (edges included)
+- `layoutSameSpot(points, options)`: `SameSpotOptions` (`mode`, `pinWidthPx`) → `SameSpotLayout`
+  (`offsets`: a `PixelOffset` per id; `groups`: `SameSpotGroup[]`). `"fan"`: 2–5 pins cascade, 6 or
+  more sit on a circle. `"group"`: 3 or more collapse into one count bubble (single-building
+  portfolios)
+- `circleOffsets(count, pinWidthPx)`, `distanceMeters(a, b)`: the circle layout; the haversine
+  distance
+- `mergePlaces(places)`: fixed places (`MapPlace`: `name`, `lat`, `lng`) within `SAME_SPOT_METERS`
+  (12 m) merged into one `PlaceMarker` (`at`, `names`)
+- `rentalAddressLine(rental, mode)`: the printed address line: `"street"` (street, postcode, town;
+  the town when the feed has no street) or `"town"`; null when the feed states nothing. Throws
+  `RentalAddressModeError` for any other value: the decision has no default, so an undecided page
+  fails its build. It decides the printed line only; the marker stays on the PMS coordinates
+- `DEFAULT_MAP_STYLE_URL`: OpenFreeMap "Bright" (no key). A third-party request: load it on the
+  visitor's click unless the site's consent covers the tile host
+- `DEFAULT_CLUSTER`: `{ radius: 54, maxZoom: 11 }`; `ClusterOptions.whenPriced` overrides it for
+  priced pins
+
+## Rental catalogue and detail model
+
+Module `rental`. The rental page's data model, built at build time from `static.rentals.getRentals`.
+Plain JSON; absence is `undefined` or `[]`; PMS strings are verbatim, and every word a page adds is
+UI copy.
+
+### `loadRentalCatalogue(sdk, options)`
+
+`options` is a `LoadRentalCatalogueOptions`. Build time. `getRentals` (one retry after 1.5 s) →
+`fetchRentalFlags` → `assignSlugs` → `adaptRental` → `rankHighlights`, sorted by name in `locale` →
+`RentalDetail[]`.
+
+| option               | default                     | meaning                                                                                                                     |
+| -------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `locale`             | required                    | the catalogue's language                                                                                                    |
+| `flags`              | `DEFAULT_FLAG_FILTERS`      | flag → dateless search key; `false` skips the flag searches                                                                 |
+| `slugOverrides`      | none                        | rental id → slug (a template's fixed short slugs); two equal overrides throw                                                |
+| `universalShare`     | 0.9                         | highlights on at least this share of the portfolio move to the back (`rankHighlights`)                                      |
+| `markup`             | `"light"`                   | `**bold**` and `- ` list lines become structure, so no asterisk reaches a guest; `"plain"`: verbatim                        |
+| `publishArrivalInfo` | `false`                     | publish `description.arrivalInfo`. On some tenants it holds key-safe codes: turn it on only after reading the feed          |
+| `propertyImages`     | `"omit"`                    | `"append"` the property's photos after the rental's own                                                                     |
+| `excludeCategories`  | none                        | amenity categories dropped besides `ALWAYS_EXCLUDED_CATEGORIES` (`Beschreibungen`, `Descriptions`, `System`)                |
+| `hideRoomAttributes` | none                        | room attribute prefixes never shown besides `HIDDEN_ROOM_ATTRIBUTES` (the floor covering)                                   |
+| `forbid`             | none                        | `RegExp[]` no published string may match; a match throws `RentalContentError` (`rentalId`, `field`, never the matched text) |
+| `report`             | one `console.warn` per kind | build-time notes (`AdaptEvent`: `duplicate-images`, `floorplan-not-rewritten`, `review-order-kept`)                         |
+
+```ts
+import {
+  cardSource,
+  createSdk,
+  loadRentalCatalogue,
+  rentalFactsMap,
+} from "@v-office/website-headless";
+
+const sdk = createSdk(SDK);
+try {
+  const rentals = await loadRentalCatalogue(sdk, { locale: "de-DE", forbid: [/tresor-?code/i] });
+  const sources = rentals.map((rental) =>
+    cardSource(rental, { rentalHref: "/unterkuenfte/{slug}" }),
+  );
+  const facts = rentalFactsMap(sources); // written as JSON for the search pages
+  console.log(Object.keys(facts).length);
+} finally {
+  await sdk.dispose();
+}
+```
+
+### `RentalDetail`
+
+- `id`, `slug`, `name`: the PMS id; the slug from `assignSlugs` (search results link with the same
+  map); `nameOrLabel` verbatim
+- `town`, `address`: `address.city` or undefined (no fallback town); `RentalAddress` (`street`,
+  `postalcode`, `city`, `province`, `country`)
+- `coords`, `type`: the PMS coordinates; the SDK-translated rental type
+- `counts`: `RentalCounts` (`guests`, `bedrooms`, `bathrooms`, `rooms`, `area`), what the feed
+  states
+- `flags`: `Partial<Record<RentalFlag, boolean>>` from `fetchRentalFlags`; a flag the backend could
+  not answer is absent
+- `distances`: `RentalDistance[]`, one per kind, in feed order
+- `images`, `floorplans`: `RentalImage[]` (`id`, `src`, `srcset?`, `caption?`, `width?`, `height?`,
+  `source`): photos deduplicated and WebP where served; floor plans as uncropped renditions
+- `description`: `DescriptionContent`: `headline?`, `intro?`, `body: RichBlock[]`, `arrivalInfo?`
+  (only with `publishArrivalInfo`)
+- `highlights`: SDK highlights, reordered by `rankHighlights`, never dropped (count echoes stay;
+  skip them with `isSpecEcho`)
+- `amenities`, `themes`, `vicinity`: `AmenityGroup[]` (`label`, `items`) without unsafe categories
+  and prose; vicinity "Themen" items; the other vicinity items that are not distances
+- `rooms`: `RentalRoom[]`: `type`, `kind` (`RoomKind`: `bedroom`, `bathroom`, `living`, `kitchen`,
+  `other`), `ordinal?`, `description?`, `beds: BedRun[]` (consecutive identical beds as a count),
+  `attributes`
+- `reviews`: `RentalReviews`: `summary?` (`ReviewSummary`: `score`, `scale`, `count`, `grade?` (the
+  PMS's own), `criteria: ReviewCriterion[]`) and `items` (`RentalReview[]` with text, newest first;
+  `reviewer` shortened)
+- `property`: `RentalPropertyInfo` (`id`, `name`, `description`, `highlights`, `images`) when the
+  feed states one
+
+### The pieces
+
+- `adaptRental(raw, options)`: one `CatalogueRental` (a `getRentals` item) → `RentalDetail`;
+  `AdaptRentalOptions` are the options above plus `slug` and `flags`. Pure apart from `report`;
+  never invents a value
+- `fetchRentalFlags(sdk, options)`: `FetchRentalFlagsOptions` (`locale`, `filters`). Build time: one
+  unfiltered baseline plus one dateless `<key>=true` search per flag → `RentalFlagsResult`
+  (`byRental`, `ignored`). A key the tenant ignores (reported in `unusedFilterKeys`, or on v9
+  matching every rental: the hub answers an unknown key with everything) or a failed search leaves
+  the flag absent; on v10 a flag every rental has stays `true`. Never fails the build
+- `DEFAULT_FLAG_FILTERS`: `{ petsAllowed: "pets", atBeach: "locBeach", inCity: "locCity" }`; a site
+  adds keys its tenant supports
+- `assignSlugs(rentals, { overrides? })`: deterministic, collision-free slugs in id order (a
+  collision gets the first 6 id characters, then the whole id)
+- `slugify(name)`: German transliteration, lowercase, hyphenated, at most 60 characters
+- `rankHighlights(rentals, { universalShare? })`: moves labels that almost every rental carries to
+  the back; reorders, never drops
+- `parseCounts({ roomSummary, highlights })`: counts from the SDK's count lines (every wording of
+  both backends and locales)
+- `parseDistances(vicinity)`, `distanceFact(distances, kinds?)`: distances in metres; the first
+  stated distance of the first kind in `kinds` (default `WATER_KINDS`: beach, sea, lake), by
+  priority, never the nearest
+- `isAdjacent(distance)`, `ADJACENT_BELOW_M`: below 25 m a distance is a statement ("Direkt am
+  Strand"), not a number
+- `isSpecEcho(label)`: a highlight that only restates a count ("4 Schlafmöglichkeiten", "61 m²")
+- `amenityPreview(rental, options?)`: the short preview before "all amenities" →
+  `{ items: AmenityPreviewItem[], total }`. `AmenityPreviewOptions`: `from` `"highlights"` (default)
+  or `"categories"`, `count` (8), `lead` (facts that lead the rows: `"distance"`, `"pets"`; default
+  none), `distanceKinds`
+- `descriptionPreview(blocks, strategy?)`: the visible part of a description → `DescriptionPreview`
+  (`shown`, `hasMore`). `PreviewStrategy`: `{ by: "sentences", budget = 320, min = 160 }` (default;
+  never ends mid-sentence), `{ by: "paragraphs", count }`, `{ by: "none" }`
+- `descriptionSummary(content, { max = 160 })`: plain text for a meta description: the first body
+  paragraph that is not a bold-only headline (feed texts often open with `**Name – Slogan**`), the
+  first paragraph when every one is, cut at a word boundary
+- `shortReviewerName(name)`, `splitReviewAuthor(author)`: "Max Muster" → "Max M."; PMS placeholders
+  → undefined (the UI says "Gast"); the author string split into name and stay
+- `newestReviewsFirst(items, locale)`: newest first by the stay month the author string names; the
+  feed order when any month does not read in `locale`
+- `webpUrl(url)`, `webpSrcset(srcset)`, `floorplanUrl(src)`: WebP for the two image hosts that serve
+  it; an uncropped floor-plan rendition (or undefined)
+
+## Cards and facts
+
+Module `cards`. One card input (`CardSource`) and the card model every renderer draws
+(`toCardModel`): showcase and result cards, the map popup, a site's own UI. Pure and deterministic
+at build and in the browser.
+
+### `CardSource`
+
+Catalogue fields from the build plus optional live fields from the results; plain JSON, so it
+crosses an island boundary. `id`, `name`, `href`, `location?`, `street?`, `regions?`, `images`
+(`CardImage`: `src`, `srcset?`, `alt` or null), `counts?`, `distances?`, `highlights?` (pill
+candidates in lead order), `stated?` (exact strings for `{ stated }` matching, never rendered),
+`ownerPills?` (the owner's labels, always first), `flags?`, `facets?`, `numbers?` (free numeric
+facts for `minimum` filters and `{ number }` matching), `rentalType?`, `rating?` (`CardRating`:
+`value`, `count`, `scale?`), `blurb?`, `coords?`, `propertyId?`; live: `price?` (`StayPrice`),
+`nights?`, `stay?` (`StayWindow`), `alternative?`, `periods?` (`AlternativePeriod[]`).
+
+- `cardSource(rental, extras?)`: build time: a `CardSource` from a `RentalDetail`.
+  `CardSourceExtras`: `href` or `rentalHref` (one is required: it throws without), `ownerPills`,
+  `highlights` (site-derived, placed before the PMS's), `blurb`, `location`, `regions`, `flags`,
+  `facets`, `numbers`
+- `rentalFactsMap(sources)`: the `RentalFactsMap` the search store takes, keyed by id; live keys and
+  `images` dropped (it ships on every search page)
+- `withRentalFacts(live, facts)`: live fields win where they state a value; facts fill the gaps;
+  non-empty facts `highlights` win (the build ranked them)
+- `loadRentalFacts(url)`: the facts map from JSON; a missing or broken file is an error, never an
+  empty set
+- `RentalFacts`, `RentalFactsMap`, `CardLiveField`: build-time facts per rental (`CardSource`
+  without `id` and the live fields), by id; the live keys
+- `StayPrice`: `total` (the stay total, never per night), `original` (the struck price),
+  `discounted`, `offerLabels` (the PMS's words, never an amount)
+- `StayWindow`, `AlternativePeriod`: the priced stay when it is not the searched dates (`source`:
+  `own-dates`, `hub-chosen`, `alternative`); one suggested window of a non-exact result with its
+  link and price
+
+### `toCardModel(source, options?, context?)`
+
+→ `RentalCardModel`: `id`, `name`, `href`, `location`, `blurb`, `images` (at most `maxImages`),
+`facts` (`CardFact[]`, each only when stated), `pills` (`CardPill[]`), `badges` (`CardBadge[]`),
+`status` (`CardStatus`: `{ kind: "offer", campaign }` beats `{ kind: "alternative-period" }`, which
+shows only on exact searches), `rating` (only with reviews), `price` (formatted by `priceCents`; the
+struck `original` is null when it equals the total after rounding), `nights`, `stay`, `periods`,
+`offerLabels`. `CardContext.exactSearch` (from `QueryShape.exactDates`) gates the alternative chip.
+
+| `CardModelOptions` | default                                      | meaning                                                                                                                              |
+| ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `facts`            | `["guests", "bedrooms", "area", "distance"]` | `FactKind[]` in display order; omit `"distance"` for no water fact                                                                   |
+| `distance`         | `{ prefer: WATER_KINDS, as: "fact" }`        | which distance, and whether it sits in the facts or as pill 0 (`as: "pill"`)                                                         |
+| `pills`            | `{ limit: 3, fill: true }`                   | `PillOptions` (below), or `false` for no row                                                                                         |
+| `badges`           | none                                         | `{ rules: BadgeRule[], limit = 2 }`: photo claims from a signal (`when: CardMatch`, `label`, `icon?`, `group?`: one badge per group) |
+| `maxImages`        | 5                                            | 1 = a still                                                                                                                          |
+| `priceCents`       | `"hide-zero"`                                | `PriceCents` for the total, the struck price and every period price                                                                  |
+| `offer`            | `"footer"`                                   | where the PMS offer labels go: `"footer"`, `"pills"`, or `"badge"` (the status chip names the first label)                           |
+
+`PillOptions`: `limit`, `fill` (false = owner pills only), `only` (an exclusive allowlist of feed
+highlights, exact equality), `prefer` (these lead the feed part), `exclude`, `rename` (display
+names), `glyphMap` (a `Glyph` per feed label; absent = text only). Owner pills always lead, outside
+`only`, `prefer` and `exclude`; a badge's label never repeats as a pill; count echoes are dropped by
+shape.
+
+### Signals: `matches(source, match)`
+
+A `CardMatch` is a `CardSignal` or `{ anyOf: CardMatch[] }` / `{ allOf: CardMatch[] }` (an empty
+`anyOf` matches nothing, an empty `allOf` everything). Nothing is inferred: no distance threshold
+stands in for a flag, no substring for a label, an absent value never matches.
+
+| signal                                                       | holds when                                              |
+| ------------------------------------------------------------ | ------------------------------------------------------- |
+| `{ flag: key }`                                              | `flags[key]` is `true`                                  |
+| `{ stated: label }`                                          | a highlight or `stated` item equals the label (trimmed) |
+| `{ guests: Range }`, `{ bedrooms: Range }`                   | the count is inside `{ min?, max? }` (inclusive)        |
+| `{ rentalType: text }`                                       | the PMS rental type equals the text                     |
+| `{ rating: { min?, minReviews? } }`                          | a real rating meets both                                |
+| `{ location: [...] }`, `{ region: [...] }`, `{ ids: [...] }` | the location, a region or the id is listed              |
+| `{ number: { key, min?, max? } }`                            | `numbers[key]` is inside the range                      |
+
+## Showcase selectors
+
+Module `showcase`. Which rentals a showcase row shows, declared as plain data in the site's data
+file and resolved at build.
+
+### `selectRentals(candidates, spec?)`
+
+→ `Selection` (`rentals`, `total` before `limit`: the honest "Alle {N}"). Steps: qualify (`match`,
+`exclude`, `minImages`) → `order` → `spreadBy` → `pin` leads → gates (`maxShare`, `failBelow`,
+`minSize`) → `limit`.
+
+| `SelectionSpec` | default  | meaning                                                                                                                        |
+| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `match`         | everyone | a `CardMatch`                                                                                                                  |
+| `pin`           | none     | ids that lead in this order, matching or not; an unknown id throws (a typo fails the build)                                    |
+| `fill`          | `true`   | `false` = the pins only                                                                                                        |
+| `exclude`       | none     | ids never shown (the page's own rental)                                                                                        |
+| `order`         | `"feed"` | `ShowcaseOrder`: `feed`, `name`, `rating`, `reviews`, `guests`, `shuffle` (with `seed`: a build date gives "random per build") |
+| `spreadBy`      | none     | `"location"` or `"street"`: round-robin across towns or buildings                                                              |
+| `minImages`     | 1        | images a rental needs                                                                                                          |
+| `limit`         | all      | rentals kept                                                                                                                   |
+| `minSize`       | 1        | fewer → an empty selection (the section self-hides); carousel rows use 3                                                       |
+| `maxShare`      | no check | a match holding more than this share of the candidates says nothing → empty                                                    |
+| `failBelow`     | never    | fewer throws at build, with the counts (a section the customer requires)                                                       |
+
+### Rows, related rentals, rotation
+
+- `buildShowcaseGroups(candidates, specs, { distinct? })`: `ShowcaseGroupSpec[]` (`id`, `label`,
+  `shortLabel?`, `icon?`, `href?`, `blurb?`, `select`) → `ShowcaseGroup[]`, the plain-JSON rows a
+  showcase renders; an empty row is omitted. `distinct`: a rental shown in an earlier row is not
+  offered to later rows
+- `selectRelated(candidates, currentId, options?)`: "more rentals nearby" for a rental page: the
+  current one excluded, near ones first. `RelatedOptions`: `prefer` `"location"` (default) or
+  `"region"`, `limit` 8, `minSize` 2 (fewer → `[]`), `minImages` 1
+- `rotationWindow(count, options)`: `RotationOptions` (`visible`, `minutes`, `now`, `seed`). The
+  indices to show now in a long row that rotates in the browser: every tile in each round of ⌈count / visible⌉ windows (a short last window refills from the round's first tiles), the same
+  window for every visitor, a new shuffle each round. Throws for `minutes <= 0`
+- `seededShuffle(items, seed)`: a deterministic Fisher–Yates
+- `resolveSearchGroups(sdk, specs, { locale, knownIds })`: build time: rows defined by curated ids
+  and/or a dateless filter query (`SearchGroupSpec`: `id`, `rentalIds?`, `filterQuery?`,
+  `pinCurated?`, `limit` 6) → `ResolvedSearchGroup[]` (`rentalIds`, `unusedFilterKeys`). One walk
+  per query; an incomplete walk rejects (the build fails and the previous build stays live)
+
+```ts
+import { buildShowcaseGroups, type ShowcaseGroupSpec } from "@v-office/website-headless";
+
+const ROWS: ShowcaseGroupSpec[] = [
+  {
+    id: "dogs",
+    label: "Mit Hund",
+    select: {
+      match: { flag: "petsAllowed" },
+      order: "rating",
+      minSize: 3,
+      maxShare: 0.8,
+      limit: 12,
+    },
+  },
+  {
+    id: "sauna",
+    label: "Mit Sauna",
+    select: { match: { anyOf: [{ stated: "Sauna" }, { flag: "sauna" }] }, spreadBy: "location" },
+  },
+];
+const groups = buildShowcaseGroups(sources, ROWS); // sources: CardSource[] from cardSource()
+```
+
+## Quote flow and availability
+
+Module `quote`. Everything the rental page's booking widget does, as one store: availability, the
+range, the party, the URL handover, the auto-quote, cancellation-policy branches, rate faults and
+the call to action. It never books: no `book()`, no `pay()`.
+
+### `createQuoteFlow(source, options)`
+
+`options` is a `QuoteFlowOptions` (the `StayPickerOptions` plus the widget's `QuoteFlowSettings`);
+returns a `QuoteFlow`.
+
+| option               | default            | meaning                                                                                                                                                                                   |
+| -------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rentalId`, `locale` | required           | the PMS rental id; the language of the PMS strings                                                                                                                                        |
+| `guests`             | `{}`               | `GuestOptions` (limits, child-age band, `defaultAdults` 2)                                                                                                                                |
+| `policyChoice`       | `"rental-page"`    | `PolicyChoiceMode`: where the guest picks the rate. `"rental-page"`: this widget offers the picker; `"checkout"`: it states the pre-selected rate's terms only                            |
+| `campaignLabels`     | `"none"`           | `CampaignLabelSource`. `"from-search"`: show the `?offer=` labels the search measured, latched to the first complete stay that is provably the one the search priced; dropped on any edit |
+| `whenUnavailable`    | `"none"`           | `WhenUnavailable`. `"next-arrival"`: offer the first arrivable day after the refused start (no extra request)                                                                             |
+| `minStayNights`      | none               | the site's minimum stay on top of the PMS's                                                                                                                                               |
+| `caps`               | none               | `{ maxGuests?, petsAllowed? }` from the catalogue (v9 availability before SDK 2.28 states no caps)                                                                                        |
+| `horizonMonths`      | 12                 | navigable months; availability is fetched one month further                                                                                                                               |
+| `autoQuoteDelayMs`   | 350                | debounce before the auto-quote                                                                                                                                                            |
+| `onEvent`            | one `console.warn` | receives `QuoteEventDetail` (`rate-fault`) once per stay                                                                                                                                  |
+| `now`                | `() => new Date()` | the clock                                                                                                                                                                                 |
+
+Lifecycle: create → `configure(settings)` if the flow already existed → `hydrate(handover)` once →
+`start()` (fetches availability; nothing is quoted before the arrival map answered).
+
+`QuoteFlowState`: `resolved` (the handover is applied: show skeletons until then), `picker`
+(`StayPickerState`), `party`, `bounds`, `agesComplete`, `stayKey`, `outcome`, `cta`,
+`chosenPolicyId` (null = the PMS pre-selection), `nextArrival`, `focusRequest` (bump: bring the
+widget into view).
+
+| `QuoteOutcome` | meaning                                                                                                                       |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `idle`         | no complete range, no adult, an age missing, or the handover still resolving                                                  |
+| `pending`      | debounce, the arrival map, the request, or the chosen rate's branch in flight                                                 |
+| `priced`       | `price` (`PriceView`), `policies` (`PolicyOffer`), `campaignLabels`, `insurance` (for custom UIs; the quote never renders it) |
+| `unavailable`  | `reason`: the SDK's, verbatim (possibly multi-line), or null                                                                  |
+| `rate-fault`   | the days are free but the rate setup is faulty (`code`); never say "not available"                                            |
+| `error`        | transport failure; only `retry()` refires                                                                                     |
+
+`QuoteCta` (`cta.kind`): `resolving`, `pick-dates`, `complete-ages`, `pending`, `book` (render
+`checkoutHref`), `change-dates`, `retry`. Every non-idle outcome carries its `stayKey`, so nothing
+from a superseded stay is shown.
+
+Actions: `picker` (the `StayPicker`, for `day(iso)`), `configure`, `hydrate`, `selectDay(iso)`,
+`resetDates()`, `setParty(patch)` (clamped; a dog cannot be added where pets are not allowed),
+`choosePolicy(id | null)` (`"rental-page"` only; costs no request, every branch is priced up front),
+`retry()`, `pickArrival(iso)` (from an occupancy calendar), `takeNextArrival()`, `requestFocus()`,
+`start()`, `dispose()`.
+
+`acquireQuoteFlow(key, create)` → `{ flow, release() }`: one flow per rental per page across islands
+(the widget, a sticky bar, an occupancy calendar). The first caller's `create` wins; a joining
+widget calls `configure` with its settings.
+
+```ts
+import {
+  acquireQuoteFlow,
+  checkoutHref,
+  createQuoteFlow,
+  readQuoteHandover,
+  writeQuoteParams,
+} from "@v-office/website-headless";
+
+// shared = shareSdk(SDK), claimed once for the page's surfaces
+const { flow, release } = acquireQuoteFlow("4711", () =>
+  createQuoteFlow(shared.sdk, {
+    rentalId: "4711",
+    locale: "de-DE",
+    guests: GUESTS,
+    policyChoice: POLICY_CHOICE,
+  }),
+);
+flow.hydrate(readQuoteHandover(new URLSearchParams(location.search)));
+flow.start();
+flow.subscribe((state) => {
+  const next = writeQuoteParams(new URLSearchParams(location.search), state);
+  if (next.toString() !== location.search.replace(/^\?/, "")) {
+    window.history.replaceState(window.history.state, "", `?${next.toString()}`);
+  }
+  const href = state.cta.kind === "book" ? checkoutHref("/buchen/haus-am-see", state) : null;
+  document.querySelector("a[data-book]")?.setAttribute("href", href ?? "#");
+});
+// teardown: release();
+```
+
+### The rental page's URL contract
+
+- `readQuoteHandover(params)`: `URLSearchParams` → `QuoteHandover` (`start`, `end`, `window` (a ±
+  window from a search link, resolved into a stay once the maps land), `party`, `policyId`,
+  `campaignLabels`, at most four). Invalid values read as absent
+- `writeQuoteParams(current, state)`: the URL after a state change: quote keys set or deleted, the
+  legacy `petsCount` and the window keys stripped once resolved, every other key kept. Before
+  `resolved` it returns `current` unchanged
+- `checkoutHref(path, state, kind?)`: `path?<stay>` from state (start, end, the party with dogs as
+  `pets`, `policy` only when chosen, `kind=option` for an option); null without a complete, priced
+  stay
+- `stayQuery(state)`: the stay alone as a query string (an enquiry link), or null
+- `QUOTE_PARAM_KEYS`, `WINDOW_PARAM_KEYS`, `CAMPAIGN_PARAM`: the keys the rental page reads and
+  writes; the ± keys resolved and stripped; `"offer"`
+
+### `createStayPicker(source, options)`
+
+One rental's arrival and departure picking over the PMS availability maps, shared by the quote, the
+checkout's date editor and an occupancy calendar. `StayPickerOptions`: `rentalId`, `locale`,
+`horizonMonths` (12), `minStayNights`, `now`. Nothing is fetched before `start()`: one arrival map
+per picker, one departure map per chosen start.
+
+`StayPickerState`: `availability` (`"loading" | "ready" | "error"`: never render a full calendar on
+error), `window`, `range`, `phase` (`"arrival" | "departure" | "complete"`), `departures`
+(`"idle" | "loading" | "ready"`), `caps` (`maxPersons`, `maxAdults`, `childrenAllowed`, `maxPets`; null where the SDK states none), `firstArrival`,
+`nights`, `revision` (bumped on every map change: re-read `day()`).
+
+`day(iso)` → `DayState`: `iso`, `kind` (`DayKind`), `selectable`, `price` (the SDK's nightly price,
+raw: format it with `dayPriceLabel`), `reason` (the SDK's block reason), `selection`
+(`"start" | "end" | "inside" | null`).
+
+| `DayKind`     | meaning                                                                                                           |
+| ------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `past`        | before today                                                                                                      |
+| `booked`      | a hard status on the arrival map: genuinely not bookable                                                          |
+| `unreachable` | departure phase: the stay would cross a booked night (kept apart so the struck set stays stable while picking)    |
+| `restricted`  | available, but a rule blocks it in this phase (no check-in, minimum stay, no check-out), or the map is not in yet |
+| `free`        | selectable now                                                                                                    |
+
+Actions: `select(iso)`, `setRange(start, end | null)` (re-validated once the arrival map is in),
+`reset()`, `configure({ minStayNights })`, `start()`, `dispose()`.
+
+### Availability and day prices
+
+- `fetchInitialAvailability(sdk, input)` (`AvailabilityWindowInput`: `rentalId`, `from`, `through`,
+  `locale`) → `InitialAvailability` (`canStart`, `hardBlocked`, `priceByDay`, `tooltipByDay`,
+  `maxPersons`, `maxAdults`, and on v9 from SDK 2.28 `childrenAllowed` and `maxPets`; null where the
+  SDK states none).
+- `fetchEndAvailability(sdk, input)` (`EndAvailabilityInput`: the window plus `start`) →
+  `EndAvailability` (`start`, `canEnd`, `hardBlocked`, `tooltipByDay`).
+- `dayPriceLabel(formatted, mode)` → the cell text, or null. `DayPrices`: `"rounded"` (whole units,
+  half up: truncation would understate every night), `"exact"` (only a zero-cents group dropped),
+  `"none"`. Cells state the nightly price, never a total.
+
+### The live quote
+
+- `fetchQuote(sdk, request)`: `QuoteRequest` (`rentalId`, `period`, `occupancy` from `occupancyOf`,
+  `locale`, `voucher?`) → `QuoteResult`: `{ status: "available", live, view }` or
+  `{ status: "unavailable", reason, code }`. Branch only on `code` (`QuoteUnavailableCode`);
+  `reason` is localized. A throw is the caller's to log
+- `adaptGuestQuote(quote)`: a `GuestQuote` → `QuoteView`: `price` (`PriceView`), `services`,
+  `policies`, `voucher?`, `insurance?` (absent without a real product)
+- `PriceView`, `PriceLine`: `total`, `totalBeforeModifiers` (the PMS's pre-modifier total; null on
+  v9), `lines` (`kind` `charge` / `sub` / `discount`, `label`, `amount`, `netAmount`: the column
+  adds up), `offerLabels`
+- `addQuoteService`, `removeQuoteService`, `selectQuotePolicy` (`(sdk, quote, id)`),
+  `clearQuoteServices(sdk, quote)`, `selectQuoteInsurance(sdk, quote, id \| null)`: selection calls
+  → `QuoteSelectionResult` (`{ ok: true, quote }` or `{ ok: false, reason? }`); a throw is logged
+  and becomes `ok: false`. Keep the previous quote on a refusal
+- `pricePolicyBranches(sdk, base, options?)`: every selectable policy (or
+  `PolicyBranchOptions.only`) priced as its own quote, sequentially → `PolicyBranch[]` (`id`,
+  `quote`, `view`); a refused branch is omitted
+- `isRateConfigurationFault(code)`, `MULTI_RATE_CODES`: `AmbiguousMultiRate` /
+  `UnresolvableMultiRate`: the stay was priced but the rate setup cannot be resolved; keep booking
+  disabled and say so
+- `stabilizeCardOrder(view, orderMap)`: pins the breakdown's block order across re-quotes (rows that
+  jump read as flakiness)
+- `QuoteAddonService`, `QuoteCancellationPolicy`, `QuotePolicyRule`, `QuoteVoucher`,
+  `QuoteInsurance`, `QuoteInsuranceOption`: the view's parts, PMS values verbatim.
+  `proposedQuantity` is a proposal, never a selection
+
+### Cancellation policies
+
+The backend returns rate definitions and never evaluates them against the stay; these rules do.
+Deadlines are whole days (`POLICY_DEADLINE_HAS_TIME` is false).
+
+- `describePolicyOffer(input)` → `PolicyOffer` for one surface. `PolicyOfferInput`: `policies`,
+  `branches` (or null), `pricesPending`, `chosenId`, `arrival`, `mode` (`PolicyChoiceMode`),
+  `surface` (`"quote" | "checkout"`), `today?`. `mode` of the result: `"choice"` (at least 2 offered
+  rates on the surface that picks: a picker), `"single"` (one rate there: one sentence), `"terms"`
+  (the other surface: the applied rate's terms), `"none"` (no policies, every v9 hub).
+- `PolicyOption`: `id`, `title` (`PolicyTitle`: `{ kind: "own", label }` for a host's policy;
+  `refundable`, `expired` or `standard` for the PMS's three built-ins, whose names read as a
+  warning), `selected`, `available`, `unavailableReason`, `total` (the branch's real total, or
+  null), `terms` (`PolicyTerms`: `deadline` > `prose` > `rules` > `none`, or `expired`), `notes`
+  (`markUp` only without a total, `processingFee`).
+- `offeredPolicies(policies, arrival?, today?)`: beside a standard rate that can no longer refund
+  anything, only rates that still can survive.
+- `freeCancellationUntil(policy, arrival, today?)`, `policyStance` (→ `PolicyStance`: `refundable`,
+  `expired`, `other`), `policyTitle`, `policyTerms(policy, options)` (`PolicyTermsOptions`:
+  `arrival`, `today`, `hasTotal`, `titled`), `isBuiltInPolicy`, `BUILT_IN_POLICY_LABELS`
+  (`BuiltInPolicyLabels`): the single rules the offer is built from.
+
+## Checkout flow
+
+Module `checkout`. The checkout from the URL handover to the paid booking, as one store: the stay
+(edited in place), the quote lifecycle, extras, rate, insurance and its document gate, voucher,
+consents, the child-age gate, `book()` and `pay()`. The live `GuestQuote` that `book()` needs is not
+serializable, so it stays in this store until then.
+
+### `createCheckoutFlow(source, options)`
+
+`options` is a `CheckoutFlowOptions`; returns a `CheckoutFlow` (`Store<CheckoutState>` plus
+`CheckoutActions`, `start()` and `dispose()`).
+
+| option               | default         | meaning                                                                                                                     |
+| -------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `rentalId`, `locale` | required        | the PMS rental id; the PMS's language                                                                                       |
+| `returnPath`         | required        | where the payment provider returns to, relative to the site origin (the site's route)                                       |
+| `handover`           | required        | `readCheckoutHandover(location.search, …)`                                                                                  |
+| `messages`           | required        | `CheckoutMessages`: `rateFault`, `unavailable`, `quoteRefreshFailed`, `voucherFailed`, `voucherRejected`                    |
+| `context`            | none            | `CheckoutContext` (`rentalName`, `location?`, `href?`, `images?`) parked in sessionStorage on `start()` for the return page |
+| `policyChoice`       | `"rental-page"` | `"rental-page"` applies the carried `?policy=`; `"checkout"` makes the offered rates choosable here (`selectPolicy`)        |
+| `requiredConsents`   | `[]`            | ids of the consent checkboxes the UI renders; each must be ticked before `book()`                                           |
+| `bankHolderFallback` | none            | the transfer account holder when the PMS sends none (the operator's name)                                                   |
+| `guests`             | none            | `GuestOptions` for the guest editor                                                                                         |
+| `minStayNights`      | none            | `setDates` refuses a shorter range                                                                                          |
+| `caps`               | none            | `{ maxGuests?, petsAllowed? }` from the catalogue, until `loadGuestCaps()` adds availability's                              |
+| `onEvent`            | none            | receives every `CheckoutEventDetail`; without it a rate fault is logged with `console.warn`                                 |
+
+`start()` parks the context and prices the handed-over stay (idempotent); `dispose()` drops every
+in-flight result.
+
+`CheckoutPhase` (`state.phase.kind`): `loading`, `missing-stay` (no complete stay arrived), `ready`,
+`unavailable` (`reason`), `error` (`retry()`), `booked` (`confirmation` is set).
+
+`CheckoutBlocker`: why the order button is off, in the order a UI should mention them. `book()` is
+refused while `blockers` is not empty.
+
+| blocker               | meaning                                                    |
+| --------------------- | ---------------------------------------------------------- |
+| `no-quote`            | no priced quote, or the phase is not `ready`               |
+| `price-pending`       | the shown price does not belong to the shown stay yet      |
+| `busy`                | a selection or a re-quote is running                       |
+| `issue`               | the last re-quote failed or found the stay unavailable     |
+| `child-ages`          | a child has no age (the age prices the stay)               |
+| `insurance-documents` | a chosen insurance's document step is unfinished (§ 7 VVG) |
+| `consents`            | a required consent is not ticked                           |
+
+`CheckoutState` also carries `kind`, `stay`, `bounds`, `view`, `services` (`CheckoutService`: the
+extra plus `count`, `canAdd`, `canRemove`), `policy` (`CheckoutPolicyState`: `applied`, `offered`,
+`all`, `freeCancellationUntil`, `offer`), `insurance` (`CheckoutInsuranceState` or null: `options`,
+`noneLabel`, `chosen`, `documents`, `requiredDocuments`, `documentsPending`), `voucher`
+(`CheckoutVoucherState`: `applied`, `error`, `checking`), `consents`, `pricePending`, `busy`,
+`issue` (`CheckoutIssue`: `reason`, `retryable`), `selectionError`, `submit`
+(`"idle" | "submitting" | "failed"`), `confirmation`, `payment` (`busyOption`, `failed`).
+
+| action                                                               | what it does                                                                                        |
+| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `setDates(start, end)`, `setParty(party)`                            | edit the stay; re-quotes after a short debounce (extras, rate and insurance carried over)           |
+| `loadGuestCaps()`                                                    | once, when the guest editor opens: the arrival map's caps (v9: children and pets rules) bound it    |
+| `changeService(id, 1 \| -1)`                                         | one unit of an extra                                                                                |
+| `selectPolicy(id)`                                                   | `policyChoice: "checkout"` only, and only to an offered rate                                        |
+| `selectInsurance(id \| null)`                                        | a selectable product, or none                                                                       |
+| `openInsuranceDocument(url)`, `confirmInsuranceDocuments(confirmed)` | the document step: every shown document opened, then the confirmation (bound to the chosen product) |
+| `applyVoucher(code \| null)`                                         | re-quote with a code; the previous quote stays when it is rejected                                  |
+| `setConsent(id, value)`, `retry()`                                   | a required consent; re-quote after a transport issue                                                |
+| `book(contact)`                                                      | ⚠ user-initiated only: creates a real booking (`BookingContact` from the guest form)                |
+| `pay(option)`                                                        | ⚠ user-initiated only: redirects to the real payment provider (not for bank transfer)               |
+
+```ts
+import {
+  CHECKOUT_EVENT,
+  createCheckoutFlow,
+  readCheckoutHandover,
+} from "@v-office/website-headless";
+
+// shared = shareSdk(SDK)
+const flow = createCheckoutFlow(shared.sdk, {
+  rentalId: "4711",
+  locale: "de-DE",
+  returnPath: "/buchen/bestaetigung",
+  handover: readCheckoutHandover(location.search, { allowOption: false }),
+  context: { rentalName: "Haus am See", href: "/unterkuenfte/haus-am-see" },
+  requiredConsents: ["terms"],
+  guests: GUESTS,
+  messages: CHECKOUT_MESSAGES, // your copy: the components' CheckoutCopy satisfies it
+  onEvent: (detail) => window.dispatchEvent(new CustomEvent(CHECKOUT_EVENT, { detail })),
+});
+flow.start();
+```
+
+### Handover
+
+- `readCheckoutHandover(search, options?)` (`CheckoutHandoverOptions`: `defaultAdults`,
+  `allowOption`) → `CheckoutHandover`: `stay` (`Stay` or null: the missing-stay card), `policyId` (a
+  seed, applied only while still offered), `kind` (`"option"` only with `allowOption`),
+  `paymentReturn` (`?return=1`). Reads `pets` and the legacy `petsCount`.
+- `checkoutSearch({ stay, policyId, kind }, current?)` → the query string for `replaceState` after
+  an edit; every other parameter of `current` is kept.
+- `BookingKind`: `"booking" | "option"` (a non-binding option, SDK `kind: "OPTION"`).
+- `Stay`: `{ start, end, party }`, serializable.
+
+### `createGuestForm(options)`
+
+The guest data form as a store (`GuestFormOptions` → `GuestForm`), with the fleet's timing: quiet
+while typing, a present value judged on leaving the field, a shown error cleared the moment it is
+fixed, empty fields judged on submit.
+
+| option            | default  | meaning                                                                                          |
+| ----------------- | -------- | ------------------------------------------------------------------------------------------------ |
+| `messages`        | required | `ValidationMessages` (the checkout copy satisfies it)                                            |
+| `countries`       | required | `CountryGroups` from `countryOptions` (build)                                                    |
+| `requiredFields`  | `[]`     | `OptionalGuestField[]` made required on top of the minimum: `salutation`, `phone`, `housenumber` |
+| `fallbackCountry` | `"DE"`   | the Land when the browser languages name none, and the dial code while no Land is chosen         |
+| `languages`       | `[]`     | `navigator.languages`, passed in by the UI                                                       |
+
+Fields (`GuestFormField`, in visual order): `salutation`, `forename`, `surname`, `email`, `phone`,
+`street`, `housenumber`, `postalcode`, `city`, `country`, `note`. `GuestFormState`: `values`,
+`errors` (shown, blocking), `warnings` (non-blocking: the street seems to carry the house number),
+`touched`, `firstInvalid`. Actions: `set(field, value)`, `blur(field)` (normalizes the phone in
+place), `submit()` → `BookingContact | null` (null with every error shown and `firstInvalid` set),
+`dispose()`.
+
+```ts
+import { createGuestForm } from "@v-office/website-headless";
+
+const guestForm = createGuestForm({
+  messages: VALIDATION_MESSAGES,
+  countries: COUNTRIES,
+  languages: navigator.languages,
+});
+const contact = guestForm.submit();
+if (contact && flow.getState().blockers.length === 0) flow.book(contact); // the guest pressed the order button
+```
+
+### Booking and payment
+
+The checkout flow calls these; a custom checkout built without the flow calls them directly.
+
+- `submitBooking(sdk, quote, contact, options)` → `BookingConfirmation` (`kind`, `bookingNumber`,
+  `schedules`, `alternatives` (settle the whole balance at once: an alternative, never added),
+  `insurancePayments`, `payable`). ⚠ Reserves for real. `SubmitBookingOptions`: `returnPath`,
+  `kind`, `bankHolderFallback`, `stay`. Writes the payment-return snapshot the moment the booking
+  number exists. Logs the SDK's cause and rethrows.
+- `PaymentScheduleView`: `kind`, `label`, `dueOn` (a complete sentence: render, never parse),
+  `paymentAt`, `lines` (`PaymentLine`), `amount`, `options` (empty = informational).
+- `isSubmittableOption(option)`: every kind but `bank_transfer`.
+- `payWithOption(sdk, option)`: ⚠ redirects or form-posts to the provider; by then the reservation
+  exists, so a failure is logged before it is rethrown.
+- `InsurancePaymentLink`: a premium owed to the insurer (`label`, `url`, `description?`), never part
+  of the schedules.
+
+### Insurance and the document gate
+
+Not configurable per site: these rules gate a real insurance contract (§ 7 VVG: the documents before
+the guest's declaration).
+
+- `selectableInsuranceOptions(insurance)`: products the checkout can complete (no per-traveler data,
+  at least one shown pre-contractual document).
+- `shownInsuranceResources(option)`: the documents listed and gated (every shown document, never a
+  label-picked subset).
+- `insuranceDocsPending(option, docs)`: every shown document opened and the product confirmed; no
+  plan chosen never blocks. `InsuranceDocsState` (`opened`, `confirmedProduct`),
+  `NO_INSURANCE_DOCS`.
+- `selectedInsuranceOption`, `insuranceProductKey` (the product label: survives a trip-value band
+  change), `insuranceIdToReapply(fresh, wanted)` (the plan to re-apply after a re-quote).
+
+### Payment return
+
+The return URL cannot carry the booking number, so a snapshot this tab wrote (sessionStorage, only
+what the page renders, no personal data) is what the return page shows.
+
+- `readPaymentReturn(search, storage?)` → `PaymentReturn`, by `state`: `"booked"` (this tab booked:
+  `snapshot` and `paymentCancelled`), `"returned"` (a provider return without a snapshot:
+  `paymentCancelled`), or `"none"` (a bare or tracking-only URL). `paymentCancelled` is the
+  provider's cancel marker (`payment=stripe&cancel=true`).
+- `BookingSnapshot`: `bookingNumber`, `kind`, `rentalName?`, `location?`, `href?`, `images?`
+  (`SnapshotImage`, at most five), `start?`, `end?`, `guests?`, `total?`.
+- `saveCheckoutContext(context, storage?)`: the flow calls it on `start()`. Never throws.
+- `CHECKOUT_CONTEXT_KEY`, `BOOKING_SNAPSHOT_KEY`: the sessionStorage keys.
+
+### Structure: `assertCheckoutStructure(root)`
+
+Headless holds the rules but no markup, so a custom checkout could drop a legal obligation while
+every unit test passes. `assertCheckoutStructure(root)` is the contract on the rendered result,
+whoever wrote it: a pure DOM check (a browser `document`, or a jsdom document in a test) that
+returns every `StructureViolation` (`requirement`: a `CheckoutRequirement`, `basis`, `detail`);
+empty = compliant. Everything is judged relative to the one order button, in DOM order. It is not
+run at publish time: a custom checkout is a review item.
+
+| `CHECKOUT_STRUCTURE` (`CheckoutStructure`: a `StructureRequirement` per id) | basis                         | check                                                                              |
+| --------------------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------- |
+| `submit-present`                                                            | § 312j Abs. 3 BGB             | exactly one `data-part="checkout-submit"`                                          |
+| `submit-wording`                                                            | § 312j Abs. 3 BGB             | its visible text matches `SUBMIT_WORDING` for its `data-booking-kind`              |
+| `total-before-submit`                                                       | § 312j Abs. 2 BGB             | a `checkout-price-total` precedes it                                               |
+| `terms-before-submit`                                                       | § 312d BGB / Art. 13 DSGVO    | a `checkout-terms` precedes it                                                     |
+| `consents-before-submit`                                                    | § 312d BGB / Art. 13 DSGVO    | every `checkout-consent` precedes it                                               |
+| `insurance-docs-before-confirm`                                             | § 7 Abs. 1 VVG, § 4 VVG-InfoV | with an insurance confirmation: every document precedes every confirmation         |
+| `premium-before-submit`                                                     | § 312j Abs. 2 BGB             | with an insurance confirmation: a `checkout-insurance-premium` precedes the button |
+
+`SUBMIT_WORDING` (`SubmitWording`, a pattern per `BookingKind`): booking
+"(zahlungspflichtig|kostenpflichtig) (buchen|bestellen|reservieren)", "jetzt kaufen", "book with
+obligation to pay", "book and pay", "pay now", "buy now"; option "unverbindlich
+(reservieren|anfragen)", "reserve without obligation", "non-binding reservation". A site may
+re-voice the label within its class; the English and option classes await a legal review. The parts
+are listed under [Part vocabularies](#checkout_parts).
+
+```ts
+import { assertCheckoutStructure } from "@v-office/website-headless";
+
+const violations = assertCheckoutStructure(document);
+for (const violation of violations)
+  console.warn(`${violation.requirement} (${violation.basis}): ${violation.detail}`);
+```
+
+## Contact form
+
+Module `forms`. The contact / enquiry form as a store. A submit posts a real request into the PMS
+(not idempotent, not reversible). The field set is the site's; how a field behaves is the package's.
+
+### `createContactForm(source, options)`
+
+`options` is a `ContactFormOptions`; returns a `ContactForm` (`Store<ContactFormState>` plus
+`ContactFormActions`). The SDK source may be lazy (`loadSharedSdk`): it is awaited on the first
+submit only, so a contact page ships no SDK until someone sends a message.
+
+| option          | default            | meaning                                                                                                                                   |
+| --------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `locale`        | required           | the request's locale                                                                                                                      |
+| `subject`       | required           | recorded on the request in the PMS; names the channel ("Anfrage Website"); at most 200 characters                                         |
+| `fields`        | required           | `ContactFieldSpec[]` in render order (`DEFAULT_CONTACT_FIELDS`: salutation, forename, surname, email, phone, country, message)            |
+| `messages`      | required           | `ContactFormMessages` (labels, required and invalid messages, the failure lines, the message-line words)                                  |
+| `supportEmail`  | required           | named in the failure line; `null` drops that half (no publishable inbox). No default: it would print one agency's inbox on another's site |
+| `initialValues` | none               | laid over the fields' defaults (prefill, a detected country)                                                                              |
+| `now`           | `() => new Date()` | the clock for "today" constraints and periods                                                                                             |
+
+`ContactFormState`: `items` (`ResolvedContactItem[]`: what validation, payload and render all walk;
+`ResolvedContactField` is its field member, with a `ContactControl`), `values` (`ContactValues`: a
+`ContactValue` per name: a string, a boolean or a `PeriodValue` `{ from, to, flexible }`), `errors`
+(field name → message, in list order), `phase` (`ContactPhase`: `editing`, `submitting`, `sent`),
+`submitError` (the line above the button), `focusTarget` (`{ name, nonce }`: focus once per nonce),
+`specProblems` (report once with `console.warn`; never thrown).
+
+Actions: `setValue(name, value)`, `blur(name)` (judges a present email), `submit()` →
+`ContactSubmitOutcome` (`{ ok: true }`, or `ok: false` with a `reason`: `busy`, `invalid`,
+`rejected` (the SDK refused the input; its issues are routed onto the fields) or `failed`; ⚠
+user-initiated only), `reset()` ("send another message"), `update(options)` (`messages`, `locale`,
+`subject`, `supportEmail`; values are kept), `dispose()`.
+
+### Field specs
+
+A `ContactFieldSpec` is one of:
+
+- `"email"`: a built-in (`ContactFieldName`: `salutation`, `forename`, `surname`, `email`, `phone`,
+  `country`, `street`, `postalCode`, `city`, `message`) as it ships;
+- `{ field: "phone", required: true }`: a built-in with decisions changed (`BuiltInFieldSpec`:
+  `required`, `label`, `width` (`FieldWidth`: `"full"` or `"half"`), `options` (salutation only),
+  `defaultValue`, plus `ValueConstraints`);
+- `{ extra: "persons", kind: "number", label: "Personen" }`: a field the API has no slot for
+  (`ExtraFieldSpec`); its answer becomes one line of the message;
+- `{ group: "Ihre Anfrage" }`: an inert heading over the fields that follow.
+
+Built-ins required by default: salutation, forename, surname, email, country, message (phone,
+street, postalCode and city are optional). The endpoint rejects an empty `salutation`, `surname`,
+`email`, `country` or `message` (`CONTACT_ENDPOINT_REQUIRED`); `contactSpecProblems(fields)` reports
+a spec that would make every submit fail.
+
+| extra `kind`                                            | message line                                                                                   |
+| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `text` (default), `multiline`, `email`, `tel`, `number` | `<prefix>: <value>`, only when answered                                                        |
+| `date`                                                  | `<prefix>: <formatIsoDate(value)>`                                                             |
+| `select` (with `options: SelectOption[]`)               | `<prefix>: <option label>`                                                                     |
+| `checkbox`                                              | `<prefix>: <checkboxYes \| checkboxNo>`, always written                                        |
+| `period` (with `allowFlexible?`)                        | `<prefix>: <from> <periodSeparator> <to>` (an open end is `periodOpen`), or `<periodFlexible>` |
+
+Extras take `extra` (`[a-z][a-zA-Z0-9]*`, not a built-in name), `label`, `required?`,
+`messagePrefix?` (default the label), `placeholder?`, `width?`, `defaultValue?`, `prefillParam?`
+(text, number, date and select only), and `ValueConstraints`: `min`/`max` (numbers, or ISO days and
+`"today"` for a date), `step`, `pattern` (the whole value, `v` flag), `maxLength`, `invalidMessage`.
+Extras listed before the `message` field form a block above the free text, extras after it a block
+below; the composed message may not exceed `CONTACT_LIMITS.message` (5000).
+
+Built-in fields are never filled from a URL: they are personal data, and a URL is logged and shared.
+
+```ts
+import {
+  createContactForm,
+  loadSharedSdk,
+  prefillFromParams,
+  resolveContactFields,
+  type ContactFieldSpec,
+} from "@v-office/website-headless";
+
+const FIELDS: ContactFieldSpec[] = [
+  "salutation",
+  "forename",
+  "surname",
+  "email",
+  { field: "phone", required: true },
+  "country",
+  { group: "Ihre Anfrage" },
+  { extra: "stay", kind: "period", label: "Reisezeitraum", allowFlexible: true },
+  { extra: "persons", kind: "number", label: "Personen", min: 1, max: 12, prefillParam: "adults" },
+  "message",
+];
+const prefill = prefillFromParams(
+  resolveContactFields(FIELDS, CONTACT_MESSAGES),
+  new URLSearchParams(location.search),
+);
+const form = createContactForm(async () => (await loadSharedSdk(SDK)).sdk, {
+  locale: "de-DE",
+  subject: "Anfrage Website",
+  fields: FIELDS,
+  messages: CONTACT_MESSAGES, // your copy: the components' ContactFormCopy satisfies it
+  supportEmail: "info@example.com",
+  initialValues: { ...prefill, country: "DE" },
+});
+```
+
+### The pure rules
+
+The store runs these; a custom UI may call them directly.
+
+- `resolveContactFields(fields, messages)`: specs → `ResolvedContactItem[]` (control, label,
+  required, width, autocomplete token, constraints, prefill parameter)
+- `validateContactValues(items, values, messages, { locale, subject, today })`: field name →
+  message, in list order; empty when the values can be sent
+- `buildContactInput(items, values, { locale, subject, messages })`: the `live.contact.submit` input
+  (the phone sent as typed)
+- `prefillFromParams(items, params)`: `prefillParam` values from the URL: trimmed, at most 200
+  characters, a number must read as one, a date must be an ISO day, a select value one of its
+  options
+- `routeContactIssues(error, items, messages, supportEmail)`: a rejected submit's
+  `error.cause.issues` onto the fields → `RoutedContactIssues` (`errors`, `submitError`, `reason`)
+- `contactSpecProblems(fields)`, `CONTACT_ENDPOINT_REQUIRED`, `CONTACT_LIMITS` (`message` 5000,
+  `subject` 200), `DEFAULT_CONTACT_FIELDS`: the spec check and its inputs
+
+### Field validation (shared with the guest form)
+
+| export                                         | rule                                                                                                                          |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `emailError(raw, messages)`                    | required, and shaped like an address with a dotted top-level domain (the endpoint stays the authority)                        |
+| `normalizePhone(raw, dial)`                    | separators → spaces, `00CC` → `+CC`, a trunk `0` → `+<dial>`; null for blank; without `dial` a national number stays as typed |
+| `phoneError(raw, dial, messages)`              | blank is valid; present, it must normalize to `+<1-9><6–14 digits>` (`phoneInvalid`), else `phoneNeedsDialCode`               |
+| `postalcodeError(raw, country, messages)`      | required; a format check only for DE (5 digits), AT and CH (4); every other country accepted as typed                         |
+| `streetWarning(street, housenumber, messages)` | non-blocking: the street ends in a number that is probably the house number                                                   |
+| `Salutation`, `SALUTATION_WIRE_VALUES`         | `female` / `male` / `unspecified` → `Frau` / `Herr` / `Keine Angabe` (one vocabulary in the PMS whatever the language)        |
+| `ValidationMessages`                           | every sentence these rules return                                                                                             |
+
+## Countries
+
+Module `countries`. The register for "Land" selects and phone prefixes. Labels come from `Intl` at
+build time; the result is plain data passed to islands.
+
+- `countryOptions(input)` (`CountryOptionsInput`: `locale`, `featured`) → `CountryGroups`
+  (`featured`, `all`, each `CountryOption = [code, label]`). `featured` defaults to
+  `DEFAULT_FEATURED_COUNTRIES` (`["DE", "AT", "CH"]`); a site adds its audience or reorders. A
+  featured code appears only in `featured`. Call it at build time.
+- `dialCode(code)` → the E.164 calling code (digits) for Europe and the common overseas origins, or
+  `undefined`: never a guessed prefix.
+- `detectCountry(countries, languages, fallback = "DE")`: preselect from `navigator.languages`;
+  non-English tags first, then English tags with an explicit region; bare `"en"` is never maximized.
+- `CountryCode`: ISO 3166-1 alpha-2; the register is never filtered.
+
+## Legal documents
+
+Module `legal`. Build time only.
+
+`fetchLegalDocuments(sdk, locale)` → `LegalDocuments` (`terms`, `privacy`: each a `LegalDocument`
+with `title` and sanitized `blocks: RichBlock[]`, or null when the workspace publishes none). v10
+reads `static.documents.getTermsAndPrivacyPolicy` (a leading headline repeating the title is
+dropped: the page draws its own). v9 returns both null without a call until the SDK serves the hub's
+documents; a v9 site renders its own terms text through `parseTextBlocks` or
+`normalizeStructuredDocument`. It throws on transport, logged with the SDK's cause: a build never
+silently ships a checkout whose terms it could not read.
+
+## Favourites
+
+Module `favorites`. The Merkliste: saved rental ids, persisted per site under the kits' key, so no
+guest loses a list when a site switches.
+
+- `favoritesStorageKey(namespace)` → `` `${namespace}-merkliste` ``. The namespace is required and
+  non-empty (it throws otherwise): pass the exact namespace the site's code resolves today, fallback
+  included. A changed key empties every guest's list.
+- `createFavorites(options)` → `Favorites`, a store the caller owns. `FavoritesOptions`:
+  `storageKey`, `storage` (default `browserStorage("local")`; null = in memory; writes fail soft),
+  `onChange` (every change, once per id).
+- `acquireFavorites(options)` → `{ favorites, release() }`: the page's shared Merkliste for the key,
+  so the `./enhance` binder, a favourites page and every heart see one set. The first claim's
+  storage wins; every claim's `onChange` receives the changes until released.
+- `Favorites` (`Store<FavoritesState>` with `ids: ReadonlySet<string>`): `ids()`, `has(id)`,
+  `toggle(id)` → the new saved state, `set(id, saved)`, `prune(known)` (drop ids the site no longer
+  knows), `reload()` (another tab changed it), `dispose()`. It satisfies the search store's
+  `FavoritesPort`.
+- `FAVORITES_EVENT` (`"merkliste:changed"`, detail `FavoritesChange`: `{ id, saved }`): dispatched
+  on `window` by `bindFavorites`.
+
+```ts
+import { acquireFavorites, favoritesStorageKey } from "@v-office/website-headless";
+
+export const FAVORITES_KEY = favoritesStorageKey("ferienhaus"); // the site's own namespace, byte for byte
+
+const { favorites, release } = acquireFavorites({ storageKey: FAVORITES_KEY });
+favorites.toggle("4711");
+// teardown: release();
+```
+
+## Shared helpers
+
+Module `shared`.
+
+### Dates and text
+
+| export                                            | what it does                                                                                      |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `IsoDay`, `IsoMonth`                              | `YYYY-MM-DD`, `YYYY-MM` (the URL spells a month `MM-YYYY`)                                        |
+| `isIsoDay(value)`                                 | a real calendar day ("2026-02-30" is not)                                                         |
+| `todayIso(now?)`                                  | today in the visitor's timezone                                                                   |
+| `addDays(day, days)`, `nightsBetween(start, end)` | calendar arithmetic without a DST shift; throw `RangeError` for a non-ISO day                     |
+| `formatIsoDate(day, locale)`                      | `"01.09.2026"` (de-DE), `"09/01/2026"` (en-US); non-ISO input returned unchanged                  |
+| `fillTemplate(template, values)`                  | replaces `{name}` tokens; an unknown token stays visible (`"{nights}"`), so a gap shows in review |
+
+### Copy templates
+
+A copy string that takes tokens is typed `Template<"count" | "label">`: the tokens the code fills, none of
+them required. It is only a type, so any string literal is assignable and a table stays plain JSON.
+
+- `fillTemplate` needs a value for every token a `Template<K>` declares and takes no other; a plain
+  `string` takes any values. A key and the code that fills it cannot drift apart.
+- `defineCopy<T>()(overrides)` checks a site's overrides of a copy interface `T` (a component's
+  `XCopy`, or `SharedCopyOverrides` one level deep): an unknown key, a wrong type and a token its key
+  does not declare are compile errors (`"{cuont} is not a token of this string"`). It returns the
+  overrides unchanged; the props take them as they are. Write a site's overrides through it, so a typo
+  fails `astro check` instead of showing `{cuont}` on the live page:
+
+  ```ts
+  import { defineCopy } from "@v-office/website-headless";
+  import type { ShowcaseCopy } from "@v-office/website-components";
+
+  export const SHOWCASE_COPY = defineCopy<ShowcaseCopy>()({ moreCount: "Alle {count} {label}" });
+  ```
+
+- `TokensOf<S>` (the tokens a literal carries) and `CheckedCopy<T, O>` (the check itself) are exported
+  for a site's own tables. A brace pair in copy always reads as a token, as it does for `fillTemplate`.
+
+### Prices
+
+`formatPriceLabel(label, cents)` trims the SDK's formatted money string without recomputing it, in
+any locale's separators (`"1.505,50 €"`, `"1,505.50 €"`, `"CHF 1'234.50"`); a shape it does not
+recognise is returned unchanged. `PriceCents`:
+
+| mode        | `"2.022,50 €"` becomes | rule                                                                      |
+| ----------- | ---------------------- | ------------------------------------------------------------------------- |
+| `show`      | `2.022,50 €`           | verbatim                                                                  |
+| `hide-zero` | `2.022,50 €`           | drop a zero cents group only (`"1.234,00 €"` → `"1.234 €"`)               |
+| `truncate`  | `2.022 €`              | cut the cents, never round up (a card never shows more than the checkout) |
+| `round`     | `2.023 €`              | half up to whole units                                                    |
+
+`parsePriceLabel(label)` → a number for ordering only, or null (never 0: 0 would sort first).
+
+### Rich text
+
+PMS text as sanitized data. Headless never renders markup: these return a block tree; the
+components' `RichText` (or a site's own markup) renders it and escapes every text.
+
+- `RichBlock`: `heading` (level 2–4), `paragraph`, `list` (`ordered`, `items`), `rule`.
+  `RichInline`: `text` (with `strong`, `em`, `code`), `break`, `link` (`href` already whitelisted:
+  https, http, mailto, tel, `/path`, `#anchor`; `external` for http(s)).
+- `parseTextBlocks(text, markup = "light")`: PMS plain text → blocks; blank lines separate
+  paragraphs. `TextMarkup` `"light"`: `**bold**` → strong, `- ` / `* ` lines → a list.
+- `normalizeStructuredDocument(nodes, options?)` (`StructuredDocumentOptions`: `title`): the SDK's
+  structured-document nodes → blocks; editor markers and context-bound tools dropped, a leading
+  heading repeating `title` removed.
+- `plainText(blocks, options?)` (`PlainTextOptions`: `max`): plain text for a meta description or an
+  alt text, cut at a word boundary.
+
+### Links, tracking, storage
+
+- `routeHref(template, params)`: `RouteParams` (`slug`, `id`): fills a `RouteTemplate`
+  (`"/unterkuenfte/{slug}"`, `"/objekt/{id}/"`). Throws when a token stays unfilled, is empty or
+  unknown: a wrong link fails the build
+- `TRACKING_PARAM_PATTERN`, `isTrackingParam(key)`: the one tracking list: `utm_*`, `mtm_*`, `pk_*`,
+  `gad_*`, `gclid`, `gbraid`, `wbraid`, `dclid`, `fbclid`, `msclkid`, `mc_eid`, `ref`, `_gl`
+- `withoutTracking(search)`: the query without tracking parameters (no `?`)
+- `shareUrl(location, options?)`: `ShareLocation` (`pathname`, `search`, `origin`) and
+  `ShareUrlOptions` (`origin`, `strip`): canonical origin + path + query without tracking (and
+  `strip`) parameters, no hash
+- `StorageLike`, `browserStorage(kind)`: Web Storage when present and writable (`"local"`,
+  `"session"`), else null (SSR, private mode, a sandboxed frame)
+- `ContactLink`: `{ label, href }` (`tel:`, `mailto:` or a page)
+- `BookableFrom`: `{ from, noticeUntil?, contact?, precision? }`: not bookable online before `from`
+  (`precision`: whether the notice names the day, the month or the year; presentation only). The search
+  form floors its pickers at `from`; the quote opens its calendar there and does not floor (the PMS
+  stays the arbiter); the notice shows while today is before `noticeUntil ?? from`
+
+### Glyphs
+
+`Glyph` is a closed vocabulary (`GLYPHS`, a `GlyphList`, lists every name): facts and rooms
+(`users`, `bed`, `bath`, `ruler`, `maximize`, `sofa`, `house`, `door`), places (`waves`, `sailboat`,
+`footprints`, `mountain`, `building`, `tractor`, `pin`), card seals (`paw`, `flame`, `droplets`,
+`trees`, `sun`, `armchair`, `home`, `key`, `star`) and amenities (`check`, `view`, `terrace`,
+`balcony`, `garden`, `grill`, `fireplace`, `pool`, `sauna`, `jetty`, `kitchen`, `oven`, `microwave`,
+`fridge`, `freezer`, `coffee`, `kettle`, `dishwasher`, `washer`, `dryer`, `heating`, `wifi`, `tv`,
+`elevator`, `parking`, `garage`, `children`, `nonSmoking`, `groups`, `noGroups`, `pets`, `beach`). A
+glyph may never carry a meaning its label does not; components map each name to an icon.
+
+## Enhance engines
+
+Entry `@v-office/website-headless/enhance`, browser only. Engines that bind server-rendered markup
+they do not own: strips, dialog layers, the rental gallery, reveal and clamp, share, image fade, the
+favourites binder and the MapLibre engines. They find what they bind by `data-part`
+([`ENHANCE_PARTS`](#enhance_parts)) and write state attributes only, never a class. Not React,
+because the description and amenities must be in the HTML, the gallery hero is the LCP element, and
+one card strip markup is rendered by Astro and by React islands alike.
+
+### `enhance(root = document, options?)`
+
+Binds every engine below `root`, once, from the layout (never per section). Idempotent: an element
+already bound (by an earlier call or a hydrated component) stays its first binder's; a second call
+binds only what is new, and its `Dispose` unbinds only that.
+
+| `EnhanceOptions` | default | binds                                                                         |
+| ---------------- | ------- | ----------------------------------------------------------------------------- |
+| `strips`         | `true`  | `[data-part="strip"]` and legacy `.card-images`, when the browser is idle     |
+| `galleries`      | `true`  | `[data-part="rental-gallery"]` with its strips and layers                     |
+| `layers`         | `true`  | `<dialog data-part="layer">`                                                  |
+| `reveals`        | `true`  | `[data-part="reveal"]` "show more" lists                                      |
+| `clamps`         | `true`  | `[data-part="clamp"]` line-clamped texts                                      |
+| `share`          | `true`  | `[data-part="share"]` / `[data-share]` buttons; an object sets `ShareOptions` |
+| `imageFade`      | `true`  | the lazy-photo fade inside every gallery                                      |
+| `favorites`      | off     | `{ storageKey }` binds the hearts and badges; without it they are not bound   |
+
+```ts
+import { enhance } from "@v-office/website-headless/enhance";
+
+// In the layout. With Astro's ClientRouter: bind on page-load, dispose before the swap.
+let dispose = () => {};
+document.addEventListener("astro:page-load", () => {
+  dispose = enhance(document, { favorites: { storageKey: FAVORITES_KEY } });
+});
+document.addEventListener("astro:before-swap", () => dispose());
+```
+
+`Dispose` (`() => void`) removes everything a binder added, window and document listeners included;
+calling it twice is safe.
+
+### Binders
+
+- `bindStrip(root, options?)`: a `strip` root with a `strip-track` (the native horizontal scroller),
+  optional `strip-prev` / `strip-next`, `strip-dots` (one child per item) and `strip-counter`; items
+  are the `strip-item`s, else the track's children. Writes `data-current` on the item, `data-active`
+  on its dot, `disabled` on the arrows, `data-engaged` / `data-dragging` on the root, the dots'
+  `aria-label` and the counter text from `data-template` (`{current}`, `{count}`). → `StripHandle`
+  (`index`, `total`, `goTo(i, "instant" | "smooth")`, `step(±1)`, `reset()`, `dispose`)
+- `StripOptions`: `paging` `"page"` (every item the track's width; default) or `"snap"`; `edges`
+  `"stop"` (default) or `"wrap"`; `drag` (mouse drag, default for snap); `deferSlides` (default
+  true: items get their `data-src` / `data-srcset` on intent). The root's `data-paging` /
+  `data-edges` set them from markup
+- `bindLayer(dialog, options?)`: a `<dialog data-part="layer">` with one URL-hash history entry per
+  open; openers are `layer-open` with `aria-controls=<dialog id>` anywhere, closers `layer-close`
+  inside. Every close (X, ESC, backdrop, Back) goes through `history.back()`; a URL hash naming the
+  layer opens it. Body scroll locked while open; focus moves only for keyboard users. Throws without
+  an id or `name`. → `LayerHandle` (`open(opener?)`, `close()`, `isOpen`, `dispose`)
+- `LayerOptions`: `name` (the hash; default the dialog id), `scroller` (reset on close; default its
+  `layer-body`), `closeOnBackdrop` (true), `onOpen(opener)`, `onClose()`
+- `bindGallery(root)`: a `rental-gallery`: its strips as page strips, its `<dialog>`s
+  `rental-gallery-grid`, `rental-gallery-viewer` and `rental-floorplan` as layers. Any element whose
+  `aria-controls` names one opens it; a viewer opener carries `data-index`. Arrow keys step the
+  viewer; the mobile strip returns to the photo last viewed; floor plans publish `--fp-ar` and are
+  warmed on hover
+- `bindReveal(root, options?)`: `RevealOptions` (`step`, `collapsible`). `reveal-item[hidden]` items
+  revealed by `reveal-more` (hides itself when nothing remains), hidden again by `reveal-less`;
+  `data-open` on the root; `data-step` on the root sets the step
+- `bindClamp(root)`: `clamp-toggle` shows only while `clamp-text` overflows its CSS line clamp;
+  toggles `data-expanded` on the root
+- `bindShare(button, { origin?, strip? })`: the canonical link (`shareUrl`): the share sheet on
+  touch devices, else the clipboard, else a prompt. After a copy: `data-state="done"` for 2 s,
+  `[data-share-idle]` / `[data-share-done]` swap, the `share-status` live region announces
+  `data-message`. `data-share-origin` and `data-share-title` from markup
+- `bindImageFade(root)`: `loading="lazy"` images get `data-loaded="fade"` when they land, `"cache"`
+  when already decoded or failed; the root carries `data-image-fade` while bound
+- `bindFavorites(root, binding)`: `FavoritesBinding` (`storageKey`). Hearts (`[data-fav]` /
+  `favorite`, id from `data-fav-id` or the enclosing `[data-result-card]`) get `aria-pressed` and
+  `data-saved`; a click toggles (unless another handler took it) and sets `data-fav-burst`; badges
+  (`[data-fav-badge]` / `favorite-badge`) show the count, `data-active="true"` above 0 (no attribute at 0;
+  `[data-active]` and `[data-active="true"]` both match), `data-fav-bump` after a change,
+  `aria-label` from `data-template` / `data-template-one`. Dispatches `merkliste:changed`
+- `withViewTransition(mutate)`: runs `mutate` in a view transition where available and motion is not
+  reduced
+- `trackInputModality()`, `focusForKeyboard(element)`: the page's pointer-vs-keyboard flag
+  (ref-counted); focus only when the last input was the keyboard
+
+### Map engines
+
+MapLibre is driven through an injected loader, so headless has no maplibre dependency
+(`typeof import("maplibre-gl")` satisfies `MapLibreLike`).
+
+- `createMapSurface(options)`: one MapLibre map on one container, built when needed → `MapSurface`
+  (`build()`, `map()`, `zoomIn()`, `zoomOut()`, `fit(bounds, padding, maxZoom)`, `resize()`,
+  `destroy()`). It puts nothing on the map
+- `MapSurfaceOptions`: `container`, `load` (`MapLibreLoader`, called at most once per page),
+  `styleUrl`, `camera` (`MapCamera`: `{ center, zoom }` or
+  `{ bounds: () => MapBounds, padding, maxZoom }`), `scrollZoom`, `start` (`"near"`: once the
+  container is near the viewport with a width; `"demand"`: on `build()` only, for click-to-load and
+  layers), `nearMargin` (`"100% 0px"`), `onReady(map, lib)`, `onView(bounds | null, byGuest)`
+- `bindResultMarkers(map, lib, options)`: the results map's markers: a clustered GeoJSON source and
+  an HTML-marker diff on every render → `ResultMarkers` (`update(points, layout, priced)`,
+  `expand(groupKey | null, pinWidthPx)`, `dispose()`). `ResultMarkersOptions`: `points`, `layout`,
+  `cluster` (`false` or `ClusterOptions`), `priced`, `onMarkers(markers)` (render into each
+  `ResultMarker`'s `body`), `onPin(id)`, `onGroup(key)`, `onBackground()`
+- `bindPlaceMarkers(map, lib, options)`: fixed markers (`PlaceMarkersOptions`: `markers` from
+  `mergePlaces`, `anchor` `"bottom"` or `"center"`, `render(body, marker)`, `popup` text or null) →
+  `Dispose`
+- `observeResultCardHover(onHover)`: which `[data-result-card]` the pointer or focus is on,
+  delegated on the document → `Dispose` (feed it to `store.setHighlighted`)
+- `markerElement({ tag, part })`, `CLICK_TOLERANCE_PX` (12): a marker's shell (MapLibre positions
+  it; never style it) and body (`data-part`, every visual); the one press-vs-drag threshold on the
+  map and on a pin
+- `MapLibreLike`, `MapLike`, `MarkerLike`, `PopupLike`, `GeoJsonSourceLike`, `MapLibreLoader`: the
+  part of maplibre-gl the engines call, structurally
+
+```ts
+import {
+  createResultsMapController,
+  DEFAULT_CLUSTER,
+  DEFAULT_FIT,
+  DEFAULT_MAP_STYLE_URL,
+  type MapBounds,
+  type SearchStore,
+} from "@v-office/website-headless";
+import {
+  bindResultMarkers,
+  createMapSurface,
+  observeResultCardHover,
+} from "@v-office/website-headless/enhance";
+
+declare const store: SearchStore; // the page's store (acquireSearchStore)
+const controller = createResultsMapController(store, { regionScope: "release-on-move" });
+const surface = createMapSurface({
+  container: document.getElementById("results-map") as HTMLElement,
+  load: () => import("maplibre-gl"),
+  styleUrl: DEFAULT_MAP_STYLE_URL,
+  camera: {
+    bounds: () => controller.getState().frame as MapBounds,
+    padding: DEFAULT_FIT.padding,
+    maxZoom: DEFAULT_FIT.maxZoom,
+  },
+  scrollZoom: false,
+  start: "demand", // build on the visitor's click: the tiles are a third-party request
+  onReady: (map, lib) => {
+    const state = controller.getState();
+    const markers = bindResultMarkers(map, lib, {
+      points: state.points,
+      layout: state.layout,
+      cluster: DEFAULT_CLUSTER,
+      priced: state.priced,
+      onMarkers: (shown) => {
+        const labels = new Map(
+          controller.getState().points.map((point) => [point.id, point.label ?? ""]),
+        );
+        for (const marker of shown)
+          marker.body.textContent =
+            marker.kind === "pin" ? (labels.get(marker.id) ?? "") : String(marker.count);
+      },
+      onPin: (id) => controller.openPin(id),
+      onGroup: (key) => controller.toggleGroup(key),
+      onBackground: () => controller.toggleGroup(null),
+    });
+    controller.subscribe((next) => markers.update(next.points, next.layout, next.priced));
+  },
+  onView: (bounds, byGuest) => controller.report("inline", { bounds, byGuest }),
+});
+document.querySelector("[data-map-open]")?.addEventListener("click", () => {
+  if (controller.getState().status === "ready") void surface.build(); // "ready" has pins, so a frame
+});
+const stopHover = observeResultCardHover((id) => store.setHighlighted(id));
+// teardown: stopHover(); surface.destroy(); controller.dispose();
+```
+
+## Part vocabularies
+
+Two `data-part` vocabularies live in headless because something other than styling depends on them:
+the legal structure of the checkout and the contract between the engines and any markup. The
+components' own `<SURFACE>_PARTS` are style hooks and live there. Renaming or removing a part or a
+marker is a major.
+
+### `CHECKOUT_PARTS`
+
+| key                 | `data-part`                   | on                                                                       |
+| ------------------- | ----------------------------- | ------------------------------------------------------------------------ |
+| `priceTotal`        | `checkout-price-total`        | the price the guest is about to owe (the summary, and above the button)  |
+| `insurancePremium`  | `checkout-insurance-premium`  | the insurance premium: a second figure beside each total, never summed   |
+| `submit`            | `checkout-submit`             | the order button; carries `data-booking-kind` (`BOOKING_KIND_ATTRIBUTE`) |
+| `terms`             | `checkout-terms`              | the terms notice, or the terms checkbox's label                          |
+| `consent`           | `checkout-consent`            | every consent checkbox                                                   |
+| `insuranceDocument` | `checkout-insurance-document` | one link per pre-contractual insurance document                          |
+| `insuranceConfirm`  | `checkout-insurance-confirm`  | the guest's receipt confirmation for those documents                     |
+
+`CheckoutPart` is one value; `BOOKING_KIND_ATTRIBUTE` is `"data-booking-kind"` (absent reads as a
+booking, so only a button that says so claims the option wording).
+
+### `ENHANCE_PARTS`
+
+| engine        | `data-part` values                                                                                                                                                                                             |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| strip         | `strip`, `strip-track`, `strip-item`, `strip-prev`, `strip-next`, `strip-dots`, `strip-counter`                                                                                                                |
+| layer         | `layer` (a `<dialog>`), `layer-open` (with `aria-controls`), `layer-close`, `layer-body`                                                                                                                       |
+| reveal, clamp | `reveal`, `reveal-item`, `reveal-more`, `reveal-less`; `clamp`, `clamp-text`, `clamp-toggle`                                                                                                                   |
+| share         | `share`, `share-status`                                                                                                                                                                                        |
+| favourites    | `favorite`, `favorite-badge`                                                                                                                                                                                   |
+| gallery       | `rental-gallery`, `rental-gallery-tile`, `rental-gallery-all`, `rental-gallery-grid`, `rental-gallery-viewer`, `rental-gallery-caption`, `rental-gallery-counter`, `rental-floorplan-open`, `rental-floorplan` |
+
+`EnhanceParts` is the object's type, `EnhancePart` one value. The map engines write their own parts
+on marker bodies: `map-pin` (with `data-id`), `map-cluster` and `map-group` (with `data-leaf-ids`,
+`|`-joined; a group also `data-expanded`), `map-marker` and `map-popup` on place maps.
+
+### Markers the engines and gates read
+
+- `GATE_MARKERS` (`GateMarkers`): attributes the platform's page gates read (fact check, room
+  measurements), rendered on the same elements as before: `data-rental-stats`,
+  `data-rental-description` … `data-rental-description-end`, `data-rental-amenities`,
+  `data-amenities-modal` … `data-amenities-overlay-end`, `data-room-attr`, `data-review-card`.
+- Legacy kit markup still binds: `.card-images` with `[data-img-track]`, `[data-img-prev]`,
+  `[data-img-next]`, `[data-dots]` (strips); `[data-share]`, `[data-share-idle]`,
+  `[data-share-done]`, `[data-share-live]` (share); `[data-fav]`, `[data-fav-id]`,
+  `[data-fav-badge]` (favourites).
+- `[data-result-card="<id>"]` names a result card: the favourites binder and the card-hover observer
+  read it.
+
+## Migrating from 0.1.x
+
+1.0.0 is a redesign with no 0.1.x compatibility. In short:
 
-## The one hard rule
+- The peer floor is `@v-office/website-sdk >=2.25.0`.
+- Surfaces take an `SdkSetup` (`{ config, options }`) instead of `SdkConfig`, and
+  `createSdk(setup, mode?)` builds from it; `shareSdk` and `loadSharedSdk` share one instance per
+  page; `sdkConfigFromEnv` reads the env and has no backend default.
+- Every SDK runner takes the SDK first: `fetchQuote(sdk, request)`,
+  `runLiveSearch(sdk, search, options)`, `submitBooking(sdk, quote, contact, options)`.
+- About 70 names of the 0.1.x root modules are gone (`sort`, `filters`, `regions`, `dates`,
+  `format`, `booking-snapshot`; `tidyPrice`, `nightlyPrice`, `SORT_OPTIONS`, `CHECKOUT_RETURN_PATH`,
+  …); `SearchResultItem` and `Stay` are reshaped (`Stay` in ISO days with a `party`).
+- `createCheckoutFlow` has `phase`, `blockers`, `onEvent` and `pay(option)`; `returnPath` and
+  `messages` are required.
+- `./enhance`: `enhance()` and the `bind*` engines replace `initImageCarousels`, `initGallery` and
+  `initHistoryOverlay`; legacy `.card-images` / `data-img-*` markup still binds.
+- New: the search form, the search store, URL codec, guests, offers, the results map controller, the
+  rental and card models, showcase selectors, the quote flow, the contact form and the favourites
+  store.
+- Unchanged on purpose: every storage key (`<namespace>-merkliste`, `voffice:checkout-context`,
+  `voffice:booking-return`), every URL key and the German sort values, so existing links and every
+  guest's Merkliste survive.
 
-**This package never constructs an SDK instance, never renders markup and never depends on a UI framework.**
-Construction needs site credentials (`src/lib/voffice.ts` in each site);
-rendering is the components' or the site's job. Every function takes the SDK
-instance (or a `getSdk` thunk) from the caller. Copy/messages are always
-parameters — the rules live here, the words live in the site.
+The release's `MIGRATION.md` and `CHANGELOG.md` (in `instructions/versions/<version>/`) carry the
+full list and what to do.
 
 ## Development
 
 ```bash
-pnpm install
+# at the repository root
+pnpm install      # website-sdk is a workspace link
+pnpm --filter @v-office/sdk-core --filter @v-office/website-sdk run build   # tsc and the tests need the built SDK
+# in packages/website-headless
 pnpm build        # tsdown → dist/ (index, enhance; .mjs + .d.mts)
 pnpm check        # tsc · oxlint · oxfmt --check
-pnpm test         # vitest, jsdom environment
+pnpm fmt          # oxfmt (writes)
+pnpm test         # vitest (jsdom), then test/dist.node.mjs on the build, imported by its name (run pnpm build first)
 ```
 
-The tests cover the pure rules (validation, insurance gate, stay helpers,
-quote adapter), the checkout flow driven as a store
-against a fake SDK, and the structural gate against rendered markup. Nothing
-books or pays for real. vitest is used because the structural gate needs a
-DOM (jsdom); the SDKs use `node --test` because they do not.
+The tests run against fake SDKs: nothing books, pays or sends for real, and no test reaches the
+network. `src/__tests__/no-site-names.test.ts` keeps customer names, domains and towns out of
+`src/`. Source files are interface-first (a `PUBLIC SURFACE` banner with every exported type and
+function documented, then the implementation); the contributor rules are in `AGENTS.md`.
 
-## Publishing
+### Releasing
 
-The **Publish** workflow (`.github/workflows/publishSDK.yml`, choice
-`website-headless`) publishes the exact version in `package.json` to npm after
-build, check and tests pass; it never bumps versions. Set the version by hand,
-merge, run the workflow. Consumers pin the exact version and receive updates
-through fleet rollouts (docs/website-platform/process/06-package-rollout.md).
+See [docs/internal/releasing/overview.md](../../docs/internal/releasing/overview.md) in the
+repository. `node .github/release/cli.mts prepare website-headless <bump>` sets the version and
+scaffolds `instructions/versions/<version>/` with the notes and `release.json`; the
+`Release packages` workflow publishes what is on `main` after build, check and tests pass. Consumers
+pin the exact version and receive updates through fleet rollouts.