@v-office/website-headless 0.0.3 → 0.1.1

package/README.md

@@ -10,7 +10,7 @@ HERE, so a site's own UI is held to the same contract.
 @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, derived manifest, enhancement engines
+                             gates, enhancement engines
 @v-office/website-components imported UI over these hooks (a site may copy and own it)
 userland                     pages, brand components, tokens, copy
 ```
@@ -20,7 +20,6 @@ userland                     pages, brand components, tokens, copy
 | 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` |
-| `…/manifest`                 | `siteManifest()` Astro integration — writes `dist/site-manifest.json` with installed package versions and per-surface states derived from the site's imports (`imported` = imports the component from website-components, `custom` = imports the surface's hook without it; see `manifest/surfaces.ts`). Three signals cross-checked per build. Node-only; import it in `astro.config` and nowhere else                                                |
 | `…/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                                                                                                                                                                                                                                                                  |
 
 The flows are stores: a UI calls `getState()`, `subscribe(listener)` and the
@@ -66,13 +65,13 @@ parameters — the rules live here, the words live in the site.
 
 ```bash
 pnpm install
-pnpm build        # tsdown → dist/ (index, manifest, enhance; .mjs + .d.mts)
+pnpm build        # tsdown → dist/ (index, enhance; .mjs + .d.mts)
 pnpm check        # tsc · oxlint · oxfmt --check
 pnpm test         # vitest, jsdom environment
 ```
 
 The tests cover the pure rules (validation, insurance gate, stay helpers,
-quote adapter, manifest derivation), the checkout flow driven as a store
+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.

package/dist/enhance/index.d.mts

@@ -15,7 +15,10 @@
  *      what the iOS swipe momentum/snap relies on; transform-based
  *      shifting can't reproduce it.
  *
- * Dots are optional and only updated when present.
+ * Dots are optional and only updated when present. Their accessible label
+ * follows `data-label-template` on the dots list (`{count}` images,
+ * `{current}` shown) — the component renders the template from its copy, so
+ * the enhancer carries no language of its own.
  */
 declare function initImageCarousels(selector?: string): void;
 declare function initRentalCarousel(viewport: HTMLElement): void;

package/dist/enhance/index.mjs

@@ -15,7 +15,10 @@
 *      what the iOS swipe momentum/snap relies on; transform-based
 *      shifting can't reproduce it.
 *
-* Dots are optional and only updated when present.
+* Dots are optional and only updated when present. Their accessible label
+* follows `data-label-template` on the dots list (`{count}` images,
+* `{current}` shown) — the component renders the template from its copy, so
+* the enhancer carries no language of its own.
 */
 function initImageCarousels(selector = ".card-images") {
 	document.querySelectorAll(selector).forEach((el) => {
@@ -49,7 +52,8 @@ function initImageCarousels(selector = ".card-images") {
 					d.removeAttribute("data-active");
 				}
 			});
-			dotsList.setAttribute("aria-label", `${total} Bilder, gerade angezeigt: ${idx + 1} von ${total}`);
+			const template = dotsList.dataset.labelTemplate;
+			if (template) dotsList.setAttribute("aria-label", template.replace(/\{current\}/g, String(idx + 1)).replace(/\{count\}/g, String(total)));
 		};
 		const goTo = (idx) => {
 			const clamped = Math.max(0, Math.min(total - 1, idx));

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { BookingPaymentOption, BookingPaymentScheduleKind, GuestQuote, GuestQuoteResult, SubmittableBookingPaymentOption, createWebsiteSDK } from "@v-office/website-sdk";
+import { BookingPaymentOption, BookingPaymentScheduleKind, GuestQuote, GuestQuoteResult, Locale, SearchSearchSort, SubmittableBookingPaymentOption, WebsiteSDKOptions, createWebsiteSDK } from "@v-office/website-sdk";
 //#region src/store/index.d.ts
 /**
  * The smallest external store that every UI framework can subscribe to:
@@ -22,6 +22,50 @@ declare function createStore<S>(initial: S): WritableStore<S>;
 //#endregion
 //#region src/sdk.d.ts
 type WebsiteSdk = ReturnType<typeof createWebsiteSDK>;
+/** Deployment stage: selects the public endpoint set below. */
+declare const STAGES: readonly ["development", "production"];
+type Stage = (typeof STAGES)[number];
+/** Public endpoints of the v10 backend per stage. */
+declare const VOFFICE_ENDPOINTS: Record<Stage, {
+  apiEndpoint: string;
+  imageBaseUrl: string;
+  searchEndpoint: string;
+}>;
+/** Public endpoints of the v9 backend per stage; API URLs derive from `apiBaseUrl`. */
+declare const HUB_ENDPOINTS: Record<Stage, {
+  apiBaseUrl: string;
+  imageProxyBaseUrl: string;
+}>;
+/** Everything the SDK needs, as plain public values — a static site has no
+ *  secret to protect. Serializable on purpose: an Astro island receives it as a
+ *  prop, so the site reads its env once (in .astro / a loader) and never inside
+ *  a component. */
+type SdkConfig = {
+  backend: "v9";
+  imageProxyBaseUrl: string;
+  v0ApiBaseUrl: string;
+  v1ApiBaseUrl: string;
+  graphqlUrl: string;
+  apiKey: string;
+} | {
+  backend: "v10";
+  imageBaseUrl: string;
+  apiEndpoint: string;
+  searchEndpoint: string;
+  accessToken: string;
+};
+/** The three values a site actually decides — backend, stage, its token — as
+ *  a full `SdkConfig`, with the endpoints the platform owns. */
+declare function sdkConfigFor({ backend, stage, token }: {
+  backend: SdkConfig["backend"];
+  stage: Stage;
+  token: string;
+}): SdkConfig;
+/** Build an SDK instance from a config (+ the SDK's options: translation
+ *  overrides, custom attributes, highlight prioritization). The caller owns the
+ *  lifecycle and calls `await sdk.dispose()` when done. The API is rate-limited
+ *  (1/s), so a browser surface keeps ONE instance for its lifetime. */
+declare function createSdk(config: SdkConfig, options?: WebsiteSDKOptions): WebsiteSdk;
 /**
  * Render `error` and its whole cause chain as indented JSON.
  *
@@ -288,7 +332,7 @@ declare function adaptGuestQuote(quote: GuestQuote): QuoteView;
 declare function fetchQuote(rentalId: string, period: {
   start: string;
   end: string;
-}, occupancy: QuoteOccupancy, sdk: WebsiteSdk, voucher?: string): Promise<QuoteResult>;
+}, occupancy: QuoteOccupancy, sdk: WebsiteSdk, locale: Locale, voucher?: string): Promise<QuoteResult>;
 type QuoteSelectionResult = {
   ok: true;
   quote: GuestQuote;
@@ -459,7 +503,7 @@ interface BookingConfirmation {
  * real. Throws on transport/backend errors (the caller renders an honest
  * retry message; nothing was necessarily booked when it throws).
  */
-declare function submitBooking(quote: GuestQuote, contact: BookingContactForm, sdk: WebsiteSdk): Promise<BookingConfirmation>;
+declare function submitBooking(quote: GuestQuote, contact: BookingContactForm, sdk: WebsiteSdk, returnPath?: string): Promise<BookingConfirmation>;
 /** True for the option kinds `submitPaymentOption` can perform in-browser
  *  (redirect / form_post / stripe_checkout). Bank transfer is display-only. */
 declare function isSubmittableOption(option: BookingPaymentOption): option is SubmittableBookingPaymentOption;
@@ -728,6 +772,13 @@ interface CheckoutFlowOptions {
     code: QuoteUnavailableCode;
     rentalId: string;
   }) => void) | undefined;
+  /** The SDK locale: the PMS answers in that language (quote lines, reasons,
+   *  policy names). */
+  locale: Locale;
+  /** Where the payment provider sends the guest back to (relative to the
+   *  site's origin). Default: the platform's `/buchen/bestaetigung`; a site
+   *  with its own return route passes it here. */
+  returnPath?: string | undefined;
 }
 interface CheckoutIssue {
   /** The stayKey the issue belongs to — a different stay re-arms the loop. */
@@ -818,18 +869,19 @@ interface ValidationMessages {
   postalcodeInvalidCH: string;
   streetHouseNumberWarning: string;
 }
-declare function normalizePhone(raw: string, dial?: string): string;
-declare function phoneError(raw: string, dial: string, c: ValidationMessages): string | undefined;
+declare function normalizePhone(raw: string, dial: string | undefined): string;
+declare function phoneError(raw: string, dial: string | undefined, c: ValidationMessages): string | undefined;
 declare function emailError(raw: string, c: ValidationMessages): string | undefined;
 declare function postalcodeError(raw: string, country: string, c: ValidationMessages): string | undefined;
 declare function streetWarning(raw: string, c: ValidationMessages): string | undefined;
 declare const VALIDATED_FIELDS: readonly ["forename", "surname", "email", "phone", "street", "postalcode", "city"];
 /** Validate one named field. Takes the selected COUNTRY plus its calling code
- *  (`dial`): two validators depend on the country — the phone via the dial
- *  code, the PLZ via its format rule. The dial code is passed in rather than
- *  looked up because the ISO→dial mapping lives with the site's country
- *  register (its localized "Land" options), not here. */
-declare function fieldError(name: string, value: string, country: string, dial: string, c: ValidationMessages): string | undefined;
+ *  (`dial`, undefined when the register has none for it): two validators depend
+ *  on the country — the phone via the dial code, the PLZ via its format rule.
+ *  The dial code is passed in rather than looked up because the ISO→dial
+ *  mapping lives with the site's country register (its localized "Land"
+ *  options), not here. */
+declare function fieldError(name: string, value: string, country: string, dial: string | undefined, c: ValidationMessages): string | undefined;
 /** Country options in the shape the site's country register provides —
  *  `[code, label]` pairs, a featured group plus the full ISO register. Kept
  *  structural so the site's own `CountryGroups` type satisfies it. */
@@ -909,4 +961,397 @@ interface StructureViolation {
 }
 declare function assertCheckoutStructure(root: ParentNode): StructureViolation[];
 //#endregion
-export { BOOKING_SNAPSHOT_KEY, BUTTON_SOLUTION_PATTERN, BookingConfirmation, BookingContactForm, BookingSnapshot, BookingSnapshotGuests, CHECKOUT_CONTEXT_KEY, CHECKOUT_PARTS, CHECKOUT_RETURN_PATH, CHECKOUT_STRUCTURE, CheckoutContext, type CheckoutFlow, type CheckoutFlowActions, type CheckoutFlowApi, type CheckoutFlowMessages, type CheckoutFlowOptions, type CheckoutFlowState, type CheckoutIssue, type CheckoutPart, type CheckoutPhase, type CountryGroupsLike, type InsuranceDocsState, InsurancePaymentLink, Listener, MULTI_RATE_CODES, NO_INSURANCE_DOCS, PaymentLine, PaymentScheduleView, PolicyBranch, PriceQuote, QuoteAddonService, QuoteCancellationPolicy, QuoteInsurance, QuoteInsuranceOption, QuoteLine, QuoteOccupancy, QuotePolicyRule, QuoteResult, QuoteSelectionResult, QuoteUnavailableCode, QuoteView, QuoteVoucher, SnapshotImage, type Stay, Store, type StructureViolation, Unsubscribe, VALIDATED_FIELDS, type ValidationMessages, WebsiteSdk, WritableStore, adaptGuestQuote, addQuoteService, assertCheckoutStructure, clearQuoteServices, createCheckoutFlow, createStore, describeSdkError, detectCountry, emailError, fetchQuote, fieldError, freeCancellationUntil, fullRefundRule, insuranceDocsPending, insuranceIdToReapply, insuranceProductKey, isRateConfigurationFault, isSubmittableOption, isoDate, logSdkFailure, normalizePhone, occupancyOf, payWithOption, phoneError, policyFreeCancellationUntil, postalcodeError, pricePolicyBranches, removeQuoteService, saveBookingSnapshot, saveCheckoutContext, selectQuoteInsurance, selectQuotePolicy, selectableInsuranceOptions, selectedInsuranceOption, shownInsuranceResources, stabilizeCardOrder, stayKeyOf, stayParams, streetWarning, submitBooking };
+//#region src/dates.d.ts
+declare function parseParam(value: string | null | undefined): Date | undefined;
+declare function parseGermanParam(value: string | null | undefined): Date | undefined;
+/** A flexible-length stay ("3–5 Nächte") as the URL carries it. Off until the
+ *  search UI offers it; the keys are reserved so a site can enable it. */
+declare const NIGHT_RANGE_ENABLED = false;
+interface NightRange {
+  min: number;
+  max: number;
+}
+declare const NIGHT_RANGE_KEYS: readonly ["minNights", "maxNights", "nights_min", "nights_max"];
+declare function parseNightRange(params: URLSearchParams): NightRange | null;
+//#endregion
+//#region src/format.d.ts
+/**
+ * Display tidy for an SDK pre-formatted German-locale price ("1.234,00 €").
+ * Nearly every stay is whole euros, so the trailing ",00" is noise — dropped only
+ * when it is the zero-cents group at the end, so real cents ("1.234,50 €") stay.
+ * A real value formatted for display, nothing fabricated; other formats pass.
+ */
+declare function tidyPrice(formatted: string): string;
+//#endregion
+//#region src/availability.d.ts
+/**
+ * The per-night price a calendar CELL shows, rounded to whole euros:
+ * "116,43 €" -> "116 €", "116,50 €" -> "117 €".
+ *
+ * A month grid is thirty-odd numbers seen at a glance and acted on by NONE of
+ * them — the guest picks a range, and the quote under the calendar then states
+ * the stay to the last cent. Two decimals in every cell buy precision nobody
+ * reads, at the one size where the digits are already tight.
+ *
+ * ROUNDS TO NEAREST, AND THAT IS THE POINT OF THE FUNCTION. Stripping the cents
+ * with a regex is one line and understates every priced night by up to 99
+ * cents, always in the direction that flatters the price. That is the shape of
+ * claim a host has to stand behind, so the error goes both ways here and is
+ * capped at 50 cents on a figure that is explicitly indicative.
+ *
+ * Parses the German format rather than doing string surgery on it: "." groups
+ * thousands, "," is the decimal. Anything that does not match that shape —
+ * another locale, no decimal group, a price the SDK formatted differently — is
+ * returned UNCHANGED. A display tidy must never turn a price it did not
+ * understand into a wrong one.
+ *
+ * This runs where `priceByDay` is BUILT rather than where a cell renders it, so
+ * every calendar fed from this map agrees: the widget's picker and the
+ * checkout's copy, which reads the same shape.
+ */
+declare function nightlyPrice(formatted: string, locale?: Locale): string;
+type VofficeSdk$1 = WebsiteSdk;
+interface InitialAvailability {
+  /** ISO dates (`YYYY-MM-DD`) the SDK flags as a valid check-in/arrival day. */
+  canStart: Set<string>;
+  /** ISO dates the rental is genuinely unbookable on (booked / closed / past the
+   *  bookable horizon — the SDK's "hard" statuses). The picker STRIKES these
+   *  through. A disabled day NOT in this set is only blocked by a rule for the
+   *  current phase (e.g. check-in-not-allowed) and is merely dimmed — it could
+   *  work in another context. */
+  hardBlocked: Set<string>;
+  /** Per-night price by ISO date — the SDK's localized string, display-tidied
+   *  to drop the noise ",00" (e.g. "120 €"). Only days the SDK prices. */
+  priceByDay: Map<string, string>;
+  /** Localized reason a day is blocked, by ISO date (the SDK's own `tooltip`,
+   *  e.g. "An diesem Tag ist keine Anreise möglich."). */
+  tooltipByDay: Map<string, string>;
+  /** Occupancy caps the SDK states for this rental (null when omitted). The
+   *  picker caps the guest stepper at these so a quote can't fail on too many
+   *  guests; the below-minimum case is left to the quote (the SDK is the
+   *  arbiter of a bookable party), so `minPersons` isn't surfaced here. */
+  maxPersons: number | null;
+  maxAdults: number | null;
+}
+interface EndAvailability {
+  /** ISO dates the SDK flags as a valid check-out/departure for the chosen
+   *  start (min-stay + checkout rules already applied by the SDK). */
+  canEnd: Set<string>;
+  /** ISO dates genuinely unbookable (booked / the range would cross an
+   *  unavailable night that is itself unavailable). STRUCK through. A disabled
+   *  day not here is only rule-blocked for this start (min-stay, check-out-not-
+   *  allowed, same-day, would-be a new start) and is merely dimmed. */
+  hardBlocked: Set<string>;
+  /** Localized reason a departure is blocked, by ISO date (min-stay-not-met,
+   *  check-out-not-allowed, range-crosses-booked, …) — the SDK's own `tooltip`. */
+  tooltipByDay: Map<string, string>;
+}
+/** Possible check-in days + occupancy caps for `rentalId` across the window.
+ *  The caller's SDK instance is reused so its 30s per-rental cache spans the
+ *  picker's lifetime. */
+declare function fetchInitialAvailability(sdk: VofficeSdk$1, rentalId: string, calculateFromDate: string, calculateThroughDate: string, locale: Locale): Promise<InitialAvailability>;
+/** Possible check-out days for a chosen `selectedStartDate`. */
+declare function fetchEndAvailability(sdk: VofficeSdk$1, rentalId: string, calculateFromDate: string, calculateThroughDate: string, selectedStartDate: string, locale: Locale): Promise<EndAvailability>;
+//#endregion
+//#region src/search.d.ts
+type VofficeSdk = WebsiteSdk;
+interface SearchImage {
+  src: string;
+  srcset?: string | undefined;
+  alt: string;
+}
+/** One window the SDK suggests for a rental it could not match exactly — a
+ *  concrete, priced, bookable stay.
+ *
+ *  EVERY FIELD IS READ OFF THE PERIOD THE SDK SENDS, never off the rental. A
+ *  promotion belongs to a (rental x window) pair — the same rental prices
+ *  undiscounted in another window — so the price and the discount are read from
+ *  the same period together, the way `mapAlternativeEntry` already resolved them
+ *  for the single window it used to render. A window whose dates the feed omits
+ *  has no label and never reaches this list; one the feed does not price shows
+ *  no price rather than a placeholder. */
+interface AlternativePeriod {
+  /** „31. Aug - 4. Sep", composed from this window's own start and end. */
+  label: string;
+  /** The detail-page link carrying THIS window's dates, so the rental opens on
+   *  the stay the row names rather than on the user's (unmatched) query. */
+  href: string;
+  /** This window's `formattedTotal`, verbatim. null when the feed omits it. */
+  priceLabel: string | null;
+  /** This window's length in nights. null when the feed omits a date. */
+  nights: number | null;
+  /** True when THIS window is discounted — the presence of the SDK's `discount`
+   *  block on this period, nothing inferred. Carried so the three discount facts
+   *  arrive together from `mapDiscount`, exactly as they do on the card. */
+  isOffer: boolean;
+  /** This window's pre-discount total, for the struck-through "was" price. */
+  offerOriginalPriceLabel: string | null;
+  /** This window's promotions, the PMS's own labels, verbatim. `amount` is
+   *  LINE-level and must not be printed beside a total — see the note on
+   *  `SearchResultItem.offers`. */
+  offers: {
+    label: string;
+    amount: string | null;
+  }[];
+}
+interface SearchResultItem {
+  /** PMS id — shared by the result card and its map marker. */
+  id: string;
+  /** `nameOrLabel`, verbatim. */
+  name: string;
+  /** `address.city`, verbatim (empty when the feed omits it). */
+  location: string;
+  /** Internal detail link — `rentalsPath` (see `runLiveSearch`) + the slug
+   *  derived from the name (URL generation), with the user's booking context
+   *  (dates + party size) appended as a query so the search selection carries
+   *  into the rental page. */
+  href: string;
+  images: SearchImage[];
+  /** Parsed out of the SDK highlights; 0 when the highlight is absent. */
+  guests: number;
+  bedrooms: number;
+  area: number;
+  /** Plain-text amenity highlights (the SDK has no icon concept), CARRIED WHOLE.
+   *
+   *  This used to be `highlights.slice(3, 6)` — the SDK opens `highlights` with
+   *  the spec stats the line above already prints, and three was a guess at how
+   *  many. It is not a constant: how many spec lines a feed states depends on
+   *  which of them the PMS has filled and on `rentalHighlightPrioritization`, so
+   *  a feed stating four leaked „55 m²" into the pill row, while the same slice
+   *  ALSO discarded good candidates below position 6.
+   *
+   *  The CARD decides now: `rental-detail-kit`'s `cardHighlights` drops the spec
+   *  block by SHAPE, then `pillRow` merges and caps. A consumer that renders this
+   *  array raw must cap it itself — it is no longer bounded here. */
+  pills: string[];
+  /** `formattedTotal`, verbatim (null when the feed omits a price). */
+  priceLabel: string | null;
+  /** Label for an SDK-provided alternative period, null for exact matches.
+   *  The FIRST of `alternativePeriods` — the SDK returns them best-first — kept
+   *  as its own field because the card's date pill names one window even where
+   *  the chooser lists several. */
+  alternativePeriodLabel: string | null;
+  /** EVERY window the SDK suggests for this card, best-first — not just the one
+   *  `alternativePeriodLabel` names. Empty on exact-match cards.
+   *
+   *  THE FEED STATES MORE THAN ONE AND THIS PROJECT RENDERED ONE. Measured
+   *  against v10 production on 2026-08-27, query
+   *  `start=2026-08-31&end=2026-09-02&adults=2`: 19 alternative entries, and 14
+   *  of them carried TWO priced windows. `mapAlternativeEntry` read
+   *  `alternativePeriods[0]` and dropped the rest, so on three cards in four a
+   *  real, priced, bookable window existed that the guest was never shown. The
+   *  same query's flexible sibling (`month=10-2026&nights=7`) returned exactly
+   *  one window on all 20 entries — so the count is a property of the QUERY, not
+   *  a constant, and every surface reading this must handle both. */
+  alternativePeriods: AlternativePeriod[];
+  /** True only when the SDK flags this item as a non-exact date match. */
+  isAlternativePeriod: boolean;
+  /** Stay length for THIS card's own window, in nights. Set only on
+   *  alternative-period cards (whose date pill describes the SDK's suggested
+   *  window, not the user's search) so the footer's "N Nächte" matches the dates
+   *  shown. null on exact-match cards — they fall back to the page-level
+   *  `nights` (their window IS the user's search). */
+  nights: number | null;
+  /** True when THIS card's window is discounted ("Angebot" badge) — the mere
+   *  PRESENCE of the SDK's `discount` block on the priced result, nothing
+   *  inferred. A promotion belongs to a (rental × window) PAIR, not to a rental:
+   *  the same rental prices undiscounted in another window, so this travels with
+   *  the price, not with the identity. Never derived from a lead-time threshold —
+   *  that number is the customer's PMS setting and moves. */
+  isOffer: boolean;
+  /** `discount.formattedOriginalTotal`, verbatim — the pre-discount total, for
+   *  the struck-through "was" price. null when the feed states a discount but no
+   *  original total: presence of a discount and the ability to price it are
+   *  different facts, so the "was" price gates on its own field. */
+  offerOriginalPriceLabel: string | null;
+  /** `discount.applied`, verbatim — the PMS's own name for each promotion and
+   *  its amount. CARRIED, NEVER AUTHORED: the label names the offer ("Last-Minute
+   *  Angebot" is what this feed states today); writing our own over it would be
+   *  fabricated data. Empty when the feed states a discount it doesn't itemise —
+   *  `isOffer` can be true with nothing here, so the label row gates on length.
+   *
+   *  ⚠ `amount` IS LINE-LEVEL, AND MUST NOT BE SHOWN BESIDE A TOTAL. It is the
+   *  modifier on the rent line, while `offerOriginalPriceLabel` and `priceLabel`
+   *  are totals — so wherever the PMS puts taxes or fees outside the discounted
+   *  line, the three do not reconcile. Measured on a live v10 quote of the same
+   *  stay the search priced: Inklusivpreis 484,35 € − 72,87 € = 411,48 €, plus
+   *  Steuern & Abgaben 10,77 €, total 422,25 €, against a search
+   *  `formattedOriginalTotal` of 497,12 €. Both endpoints agree on every figure;
+   *  the real total saving is 74,87 € because the tax shrank too, while `amount`
+   *  states the rent's 72,87 €. `search-results-kit` renders the LABEL alone for
+   *  this reason — it did render the amount, in 1.10.0, and that was the bug.
+   *  The field STAYS because it is correct DATA: a surface that shows the rent
+   *  line itself may pair it with that line. Do not "fix" it by computing
+   *  `original − total` — that number is nowhere in the feed. */
+  offers: {
+    label: string;
+    amount: string | null;
+  }[];
+  /** True when the rental is newly listed ("Neu" badge). The live search summary
+   *  feed carries no listing-age signal — the SDK's search result
+   *  (`toSearchOutputItem`) exposes only id/name/timeZone/address/images/
+   *  highlights/formattedTotal, with no created/published/firstListed field — so
+   *  this is always false today and the badge self-hides; wire it to a real SDK
+   *  source (e.g. a per-rental created/published date) when search exposes one.
+   *  Never fabricate it — straight-through rule. */
+  isNew: boolean;
+  /** `property.id`, verbatim (null when the rental belongs to no property). The
+   *  v-office "Property" is the Anlage/complex a rental sits in; the home page's
+   *  Anlage cards link to `/suchen?property=<id>`, and the shared search store
+   *  scopes its snapshot to this id client-side (the live search has no property
+   *  filter key — verified: `property=` lands in `unusedFilterKeys`). Same
+   *  scoping model as favorites mode. */
+  propertyId: string | null;
+  /** `location`, verbatim (null when the feed omits coordinates). */
+  coords: {
+    lat: number;
+    lng: number;
+  } | null;
+}
+interface SearchPayload {
+  items: SearchResultItem[];
+  /** Stay length from the user's start/end query, or null when undated. */
+  nights: number | null;
+  /** Count of SDK-provided alternative-period results in this page. */
+  alternativePeriodCount: number;
+  /** `pageInfo.nextCursor`, verbatim — opaque, passed straight back to fetch
+   *  the next page. null when the feed omits it (last page / no more). */
+  cursor: string | null;
+  /** `pageInfo.hasNextPage`, verbatim. */
+  hasNextPage: boolean;
+}
+interface LiveSearchOptions {
+  /** Path of the site's rental detail pages, prefixed to every result `href`
+   *  before the slug (e.g. `/de/unterkuenfte`). A trailing slash is tolerated.
+   *  Default: `DEFAULT_RENTALS_PATH`. */
+  rentalsPath?: string | undefined;
+}
+/** The rental detail pages' path when the caller names none — the site
+ *  starter's German route. A site whose pages live elsewhere (a locale prefix,
+ *  another segment) passes its own `rentalsPath` to `runLiveSearch`. */
+declare const DEFAULT_RENTALS_PATH = "/unterkuenfte";
+/**
+ * Run a live search for the given URL query string (e.g.
+ * `window.location.search`). Builds the SDK query from the picker params,
+ * calls the rate-limited live API once, and maps the items. Pass an SDK
+ * instance to reuse its internal cache across an eager pagination walk;
+ * otherwise this function owns a short-lived instance for a single call.
+ *
+ * Pass `cursor` (the previous page's `pageInfo.nextCursor`, treated as
+ * opaque) to fetch the next page. The returned `cursor`/`hasNextPage` are
+ * the SDK's `pageInfo` straight through, so the caller can keep paging.
+ *
+ * `options.rentalsPath` is the path the site serves its rental detail pages
+ * under — the part of every result `href` before the slug. Routing is the
+ * site's decision (a locale prefix like `/de/unterkuenfte`, another segment),
+ * so it arrives as an option the way `SearchBar.action` and `Quote.checkoutPath`
+ * do; `locale` never implies it. Defaults to `DEFAULT_RENTALS_PATH`.
+ */
+declare function runLiveSearch(sdk: VofficeSdk, searchString: string, locale: Locale, cursor?: string | null, options?: LiveSearchOptions): Promise<SearchPayload>;
+//#endregion
+//#region src/sort.d.ts
+/** URL param. A client-side scope like `property`/`region`, NOT an SDK query
+ *  key — it is dropped from the SDK query string in search.ts's DROP_KEYS and
+ *  travels as the separate `sort` input instead. */
+declare const SORT_PARAM = "sort";
+type SortValue = "empfohlen" | "preis-auf" | "preis-ab";
+/** The backend's own order. Emits no `sort` at all, so it is exactly the
+ *  ordering the page has always shown. Typed as the literal (not `SortValue`)
+ *  so `value === DEFAULT_SORT` narrows the rest away for `SDK_SORT`. */
+declare const DEFAULT_SORT: "empfohlen";
+interface SortOption {
+  value: SortValue;
+  label: string;
+  /** Needs a period + occupancy, or the SDK rejects it before transport. */
+  pricedOnly?: boolean;
+}
+declare const SORT_OPTIONS: readonly SortOption[];
+/** The sort in the URL, or the default when absent/unknown. */
+declare function activeSort(search: string): SortValue;
+/**
+ * Can this query be priced? Mirrors the SDK's own precondition: a fixed period
+ * (`start`+`end`) or a flexible window (`dates`/`month`/`weekend`), AND
+ * occupancy. Without both, the backend returns no totals and the SDK rejects
+ * price ordering before it reaches the wire.
+ *
+ * Period keys count only with a value: the search's `buildQuery` drops empty
+ * params (`?start=&end=`), so a key that is merely present would pass this
+ * gate and still reach the SDK undated. `weekend` is the exception — it is a
+ * presence-only flag on both sides.
+ */
+declare function isPricedQuery(search: string): boolean;
+/** Is this option selectable for the current query? */
+declare function isSortAvailable(option: SortOption, search: string): boolean;
+/**
+ * The `sort` to hand the SDK for this URL, or `undefined` for the backend's
+ * own order. Falls back to `undefined` (rather than throwing) when a price
+ * sort survives in the URL after the dates were cleared.
+ */
+declare function resolveSdkSort(search: string): SearchSearchSort | undefined;
+//#endregion
+//#region src/filters.d.ts
+/**
+ * The search filter model the UI consumes — client-safe, no SDK import. The SDK
+ * exposes filter definitions via `getFilters`; a site curates them at build time
+ * into `FilterDef[]` (which keys, in which order) and hands the list to the
+ * results surface. Boolean filters toggle, integer filters are a lower bound.
+ */
+type FilterType = "boolean" | "int";
+interface FilterDef {
+  /** The URL query key, which is also the SDK's search parameter key. */
+  key: string;
+  label: string;
+  type: FilterType;
+  /** Only meaningful for `int` filters. */
+  min: number;
+  max: number;
+}
+interface ActiveFilter {
+  key: string;
+  label: string;
+}
+/** A boolean filter is active when its param is present and truthy. */
+declare const isBooleanFilterActive: (value: string) => boolean;
+/**
+ * The filters currently applied in the query, in the order the defs are
+ * declared — the removable chips. An `int` label is prefixed with the localized
+ * "minimum" wording, because its value is a lower bound.
+ */
+declare function activeFiltersFromQuery(searchParams: URLSearchParams, defs: readonly FilterDef[], minimumPrefix: string): ActiveFilter[];
+/** The dog-friendly search as the URL carries it: `pets=true` (or a count) and,
+ *  from an older vocabulary, `petsCount=N`. Read by the live search. */
+declare const PETS_PARAM = "pets";
+declare const PETS_COUNT_PARAM = "petsCount";
+declare function petsCountInQuery(search: string): number;
+//#endregion
+//#region src/regions.d.ts
+/**
+ * The "Region" scope of the live search.
+ *
+ * "Region" is a v10 custom attribute (MULTI_SELECT, PUBLIC) set per rental in
+ * v-office — e.g. Duhnen, Döse. The live search has no usable server-side key
+ * for it: the SDK filters a custom attribute only on an exact raw match of its
+ * stored JSON-array value, and registering the definition would fold a
+ * `Region: ["…"]` string into every card and detail highlight (verified). So
+ * `region` is dropped from the SDK query (search.ts, DROP_KEYS) and applied
+ * here, client-side, against the per-rental regions the site hydrates from its
+ * static catalogue at build time — the same channel as the other facts the
+ * search projection does not carry.
+ */
+/** URL query key carrying the active region scope. Repeatable: several
+ *  `region=<name>` values OR together (show rentals in ANY selected region). */
+declare const REGION_PARAM = "region";
+/** The regions active in a URL query string: the `region` values, trimmed,
+ *  de-duplicated, order preserved. Absent or empty → `[]`. */
+declare function activeRegions(search: string): string[];
+/**
+ * The results inside the region scope. A rental may carry several regions
+ * (MULTI_SELECT) and matches when any of them is selected; with no active
+ * region every result stays. A rental the map does not know is outside every
+ * region, so it drops out of a scoped search rather than passing unseen.
+ */
+declare function scopeToRegions<T extends {
+  id: string;
+}>(items: readonly T[], active: readonly string[], regionsByRentalId: (id: string) => readonly string[] | undefined): T[];
+//#endregion
+export { ActiveFilter, AlternativePeriod, BOOKING_SNAPSHOT_KEY, BUTTON_SOLUTION_PATTERN, BookingConfirmation, BookingContactForm, BookingSnapshot, BookingSnapshotGuests, CHECKOUT_CONTEXT_KEY, CHECKOUT_PARTS, CHECKOUT_RETURN_PATH, CHECKOUT_STRUCTURE, CheckoutContext, type CheckoutFlow, type CheckoutFlowActions, type CheckoutFlowApi, type CheckoutFlowMessages, type CheckoutFlowOptions, type CheckoutFlowState, type CheckoutIssue, type CheckoutPart, type CheckoutPhase, type CountryGroupsLike, DEFAULT_RENTALS_PATH, DEFAULT_SORT, EndAvailability, FilterDef, FilterType, HUB_ENDPOINTS, InitialAvailability, type InsuranceDocsState, InsurancePaymentLink, Listener, LiveSearchOptions, type Locale, MULTI_RATE_CODES, NIGHT_RANGE_ENABLED, NIGHT_RANGE_KEYS, NO_INSURANCE_DOCS, NightRange, PETS_COUNT_PARAM, PETS_PARAM, PaymentLine, PaymentScheduleView, PolicyBranch, PriceQuote, QuoteAddonService, QuoteCancellationPolicy, QuoteInsurance, QuoteInsuranceOption, QuoteLine, QuoteOccupancy, QuotePolicyRule, QuoteResult, QuoteSelectionResult, QuoteUnavailableCode, QuoteView, QuoteVoucher, REGION_PARAM, SORT_OPTIONS, SORT_PARAM, STAGES, SdkConfig, SearchImage, SearchPayload, SearchResultItem, SnapshotImage, SortOption, SortValue, Stage, type Stay, Store, type StructureViolation, Unsubscribe, VALIDATED_FIELDS, VOFFICE_ENDPOINTS, type ValidationMessages, WebsiteSdk, WritableStore, activeFiltersFromQuery, activeRegions, activeSort, adaptGuestQuote, addQuoteService, assertCheckoutStructure, clearQuoteServices, createCheckoutFlow, createSdk, createStore, describeSdkError, detectCountry, emailError, fetchEndAvailability, fetchInitialAvailability, fetchQuote, fieldError, freeCancellationUntil, fullRefundRule, insuranceDocsPending, insuranceIdToReapply, insuranceProductKey, isBooleanFilterActive, isPricedQuery, isRateConfigurationFault, isSortAvailable, isSubmittableOption, isoDate, logSdkFailure, nightlyPrice, normalizePhone, occupancyOf, parseGermanParam, parseNightRange, parseParam, payWithOption, petsCountInQuery, phoneError, policyFreeCancellationUntil, postalcodeError, pricePolicyBranches, removeQuoteService, resolveSdkSort, runLiveSearch, saveBookingSnapshot, saveCheckoutContext, scopeToRegions, sdkConfigFor, selectQuoteInsurance, selectQuotePolicy, selectableInsuranceOptions, selectedInsuranceOption, shownInsuranceResources, stabilizeCardOrder, stayKeyOf, stayParams, streetWarning, submitBooking, tidyPrice };