@v-office/website-headless 0.1.1 → 1.0.0

package/dist/sdk-claim-CsYFzvEc.mjs

@@ -0,0 +1,72 @@
+import { k as acquireShared } from "./parts-CS1VBrPt.mjs";
+//#region src/sdk/errors.ts
+/** Nesting deeper than this is cut: a cause chain is a handful of levels, never more. */
+const MAX_DEPTH = 6;
+/**
+* Every failure arrives as a `CoreSDKError` (`source`, `operation`, `message`, `cause`), and the
+* sentence that names the fault is in `cause` — a GraphQL `errors` array, a transport
+* `{ status, statusText, body }`, or a nested `CoreSDKError`. `console.error(error)` does not print it,
+* and neither does `Object.entries`: `Error` declares `name`, `message` and `cause` non-enumerable
+* (verified on the real class: `Object.keys(new CoreSDKError(…))` is `["source", "operation", "_tag"]`).
+* So those three are read by hand, `cause` first after the message so the reason reads under it.
+*/
+function unwrap(value, depth, seen) {
+	if (value === null || typeof value !== "object") return value;
+	if (depth > MAX_DEPTH) return "[truncated]";
+	if (seen.has(value)) return "[circular]";
+	seen.add(value);
+	if (Array.isArray(value)) return value.map((entry) => unwrap(entry, depth + 1, seen));
+	const out = {};
+	if (value instanceof Error) {
+		out["name"] = value.name;
+		out["message"] = value.message;
+		if (value.cause !== void 0) out["cause"] = unwrap(value.cause, depth + 1, seen);
+	}
+	for (const [key, entry] of Object.entries(value)) if (key !== "stack") out[key] = unwrap(entry, depth + 1, seen);
+	return out;
+}
+/** See {@link DescribeSdkError}. */
+const describeSdkError = function describeSdkError(error) {
+	try {
+		return JSON.stringify(unwrap(error, 0, /* @__PURE__ */ new WeakSet()), null, 2) ?? String(error);
+	} catch {
+		return String(error);
+	}
+};
+/** See {@link LogSdkFailure}. */
+const logSdkFailure = function logSdkFailure(scope, error) {
+	console.error(`[sdk] ${scope} failed:`, describeSdkError(error));
+};
+//#endregion
+//#region src/sdk/claim.ts
+/** See {@link SdkInput}. */
+const sdkInput = function sdkInput(setup, mode) {
+	const options = mode === "all-rentals-at-once" ? {
+		...setup.options,
+		searchAllRentalsAtOnce: true
+	} : setup.options;
+	return options ? {
+		config: setup.config,
+		options
+	} : { config: setup.config };
+};
+/** JSON with object keys sorted at every level, so two equal setups written in a different key order
+*  share one instance. `undefined` members drop out, as in JSON. */
+function stableJson(value) {
+	return JSON.stringify(value, (_key, entry) => entry !== null && typeof entry === "object" && !Array.isArray(entry) ? Object.fromEntries(Object.entries(entry).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) : entry);
+}
+/** See {@link ClaimSdk}. */
+const claimSdk = function claimSdk(setup, mode, construct) {
+	const claim = acquireShared("sdk", stableJson({
+		setup,
+		mode
+	}), () => construct(setup, mode), (sdk) => {
+		sdk.dispose().catch((error) => logSdkFailure("sdk.dispose", error));
+	});
+	return {
+		sdk: claim.value,
+		release: claim.release
+	};
+};
+//#endregion
+export { logSdkFailure as i, sdkInput as n, describeSdkError as r, claimSdk as t };

package/dist/sdk-create-Bsd9lqj_.mjs

@@ -0,0 +1,9 @@
+import { n as sdkInput } from "./sdk-claim-CsYFzvEc.mjs";
+import { createWebsiteSDK } from "@v-office/website-sdk";
+//#region src/sdk/create.ts
+/** See {@link CreateSdk}. */
+const createSdk = function createSdk(setup, mode = "default") {
+	return createWebsiteSDK(sdkInput(setup, mode));
+};
+//#endregion
+export { createSdk as t };

package/instructions/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+<!-- generated by `node .github/release/cli.mts index`; do not edit by hand -->
+
+Release notes of `@v-office/website-headless`, newest first. Each version has its own directory.
+
+- `versions/1.0.0/CHANGELOG.md`: release notes for 1.0.0
+- `versions/0.2.0/CHANGELOG.md`: release notes for 0.2.0
+- `versions/0.1.1/CHANGELOG.md`: release notes for 0.1.1

package/instructions/MIGRATION.md

@@ -0,0 +1,9 @@
+# Migration
+
+<!-- generated by `node .github/release/cli.mts index`; do not edit by hand -->
+
+Migration guides of `@v-office/website-headless`, newest first. Apply them in order when skipping versions.
+
+- `versions/1.0.0/MIGRATION.md`: Migration: 0.2.0 to 1.0.0
+- `versions/0.2.0/MIGRATION.md`: Migration: 0.1.1 to 0.2.0
+- `versions/0.1.1/MIGRATION.md`: Migration to 0.1.1

package/instructions/versions/0.1.1/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog: 0.1.1
+
+Baseline of the shipped release notes for `@v-office/website-headless`. The package is the framework-free behavior layer of the website platform: the checkout flow as a store, validation and insurance rules, the checkout's structural requirements and the progressive-enhancement engines.
+
+Changes before 0.1.1 are recorded in this repository's git history only. From
+this version on, every release carries its own `CHANGELOG.md` and
+`MIGRATION.md` in `instructions/versions/<version>/`.

package/instructions/versions/0.1.1/MIGRATION.md

@@ -0,0 +1,4 @@
+# Migration to 0.1.1
+
+No changes required. 0.1.1 is the version that was published when the shipped
+release notes were introduced; consumers already on it stay as they are.

package/instructions/versions/0.1.1/release.json

@@ -0,0 +1,3 @@
+{
+  "componentsAffectedByHeadlessChange": []
+}

package/instructions/versions/0.2.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog: 0.2.0
+
+The initial availability of the booking date picker now carries the v9 rules for children and
+pets, so a guest selector can stop offering a party the quote would refuse.
+
+## Added
+
+- `fetchInitialAvailability` returns `childrenAllowed` and `maxPets` in its
+  `InitialAvailability`. On v9 with `@v-office/website-sdk` 2.28.0 or later,
+  `childrenAllowed` is `false` when the rental takes no children, babies included, and
+  `maxPets` is the most pets the quote accepts, `0` for none. Both are `null` on v10, with an
+  older SDK and when the rental states no rule; `null` means no limit.
+
+## Unchanged
+
+- `maxPersons` and `maxAdults` keep their meaning. On v9 they carry the rental's limits from
+  `@v-office/website-sdk` 2.28.0 on, where they were `null` before.

package/instructions/versions/0.2.0/MIGRATION.md

@@ -0,0 +1,16 @@
+# Migration: 0.1.1 to 0.2.0
+
+## 1. Upgrade
+
+```sh
+pnpm add @v-office/website-headless@0.2.0
+```
+
+No changes are required for code that reads `fetchInitialAvailability`. Code that builds an
+`InitialAvailability` itself, such as a test fixture, adds `childrenAllowed: null` and
+`maxPets: null`.
+
+A site with its own guest selector can use the two fields: offer neither children nor babies
+when `childrenAllowed` is `false`, and cap pets at `maxPets`, hiding them at `0`. Keep a
+selection the guest arrived with visible until they remove it, so a party the quote refuses
+can still be corrected.

package/instructions/versions/0.2.0/release.json

@@ -0,0 +1,3 @@
+{
+  "componentsAffectedByHeadlessChange": ["quote", "booking"]
+}

package/instructions/versions/1.0.0/CHANGELOG.md

@@ -0,0 +1,170 @@
+# Changelog: 1.0.0
+
+1.0.0 is a redesign of the behaviour layer, with no 0.x compatibility. Every behaviour the
+website surfaces need now lives here as a store or a pure rule (the search form, the live search,
+the results map, the quote, the checkout and the contact form), every runner takes the SDK first,
+one SDK instance serves a whole page, and the fleet's per-site rulings became options with safe
+defaults instead of one site's behaviour for everyone. `@v-office/website-components` 1.0.0 renders
+these stores; a site that builds its own UI uses the same stores and is held to the same rules.
+Storage keys, URL keys and the German sort values are unchanged, so links and every guest's
+Merkliste survive the switch. `MIGRATION.md` lists what to change, in order.
+
+## Added
+
+### SDK and wiring
+
+- `SdkSetup` (`{ config, options? }`): the one plain-data SDK input every surface takes, written
+  once per site.
+- `sdkConfigFromEnv(env)` with `SDK_ENV` and `SdkEnvError`: the fleet's env names
+  (`CMS_BACKEND`, `CMS_STAGE`, `HUB_API_KEY`, `HUB_GRAPHQL_URL`, `HUB_V0_API_BASE_URL`,
+  `HUB_V1_API_BASE_URL`, `IMAGE_PROXY_BASE_URL`, `VOFFICE_LOCAL_DEV_ACCESS_TOKEN`,
+  `VOFFICE_API_ENDPOINT`, `VOFFICE_SEARCH_ENDPOINT`, `VOFFICE_IMAGE_BASE_URL`) to an
+  `SdkConfig`. No backend default; one error names every missing or conflicting variable, never a
+  value.
+- `shareSdk(setup, mode?)` and `loadSharedSdk(setup, mode?)`: every surface on a page with an
+  equal setup gets the same instance, so one 1 request/second queue and one cache serve the
+  page. `loadSharedSdk` imports the SDK on first use. `resolveSdk`, `SdkSource` (an instance or a
+  getter) and `SdkMode` (`"default"`, `"all-rentals-at-once"`).
+- `walkSearchPages`, `fetchSearchPage`, `SEARCH_PAGE_SIZE`: the one paged walker every search
+  uses, 100 results per request.
+
+### Stores and rules, per surface
+
+- **Search form:** `createSearchForm` (the bar's state, a GET form that never calls the SDK),
+  `createDateSearch`, `createGuestSearch`, `describePeriod`, `formatStayRange`, and the rental
+  name jump (`matchRentals`, `loadRentalIndex`, `rentalIndexEntries`).
+- **URL parameters:** `SEARCH_PARAMS`, `readSearch`, `writeSearch`, `searchHref`,
+  `SearchContract` (`backend`, `nightRangeSearch`, `aliases`), `readParty`, `partyPairs`.
+- **Guests:** one party model (`Party`, `GuestOptions`, `GuestLimits`, `guestBounds`,
+  `clampParty`, `agesComplete`) for the search bar, the quote and the checkout. `limits.pets`: 0 =
+  no dogs, 1 = a toggle, more = a stepper. `GuestCaps` takes 0.2.0's v9 `childrenAllowed` and
+  `maxPets`; `guestBounds` applies them as 0.2.0's components did.
+- **Search store:** `createSearchStore` (the page's one live search, with filters, sort, chips,
+  favourites scope and the empty and error outcomes), `acquireSearchStore`, `connectSearchStore`,
+  result items for prerendered listings (`catalogueResultItem`, `resultCardSource`), sort
+  (`SortKey`, `SORT_URL_VALUE`, `DEFAULT_SORT_OPTIONS`, `sortResults`), filter curation
+  (`FilterSpec`, `resolveFilters`, `measureFilters`), links (`handoverQuery`,
+  `externalSearchHref`, `sanitizeSearch`, `resultsQueryFlagScript`), `describeOutcome`.
+- **Offers:** `offersWindowQuery`, `findOfferWindows`, `findCampaignStart`, `campaignGroup`,
+  `campaignChips`, `offerWindowHref`; result links carry `offer=` labels to the rental page.
+- **Results map:** `createResultsMapController` over the search store, pins, framing, same-spot
+  layout, and the address decision `rentalAddressLine` with `RentalAddressMode` (no default).
+- **Rental catalogue:** `loadRentalCatalogue(sdk, { locale, … })` gives `RentalDetail[]` for the
+  rental pages, JSON-LD and cards; `fetchRentalFlags`, slugs, counts, distances, amenity and
+  description previews, reviewer names, image URL rules.
+- **Cards:** `CardSource` and `cardSource(rental, { href, … })`, the one card input;
+  `toCardModel`, `rentalFactsMap`, `loadRentalFacts`, `matches`.
+- **Showcase:** `buildShowcaseGroups`, `selectRentals`, `selectRelated`, `rotationWindow`,
+  `resolveSearchGroups`.
+- **Quote:** `createQuoteFlow` and `acquireQuoteFlow` (the booking widget as a store),
+  `createStayPicker`, `dayPriceLabel` with `DayPrices`, the rental page's URL contract
+  (`readQuoteHandover`, `writeQuoteParams`, `checkoutHref`, `stayQuery`), the cancellation-policy
+  rules (`describePolicyOffer`, `offeredPolicies`, `policyStance`, `policyTitle`, `policyTerms`,
+  `PolicyChoiceMode`), `BookableFrom` for a site that is not bookable online yet.
+- **Checkout:** `readCheckoutHandover`, `checkoutSearch`, `createGuestForm` (the guest data form
+  with the fleet's validation timing), `readPaymentReturn`, option bookings (`?kind=option`).
+- **Contact form:** `createContactForm` with field specs, validation and the PMS submit;
+  `DEFAULT_CONTACT_FIELDS`, `CONTACT_LIMITS`.
+- **Favourites:** `favoritesStorageKey(namespace)`, `createFavorites`, `acquireFavorites`.
+- **Countries and legal documents:** `countryOptions`, `dialCode`, `fetchLegalDocuments`.
+- **Shared helpers:** `IsoDay` / `IsoMonth` and their arithmetic, `formatPriceLabel` with
+  `PriceCents`, `parseTextBlocks` and `normalizeStructuredDocument` (sanitized PMS text),
+  `routeHref`, `browserStorage`, the tracking-parameter list, the closed `GLYPHS` vocabulary.
+
+### Events and part vocabularies
+
+- `QUOTE_EVENT` (`voffice:quote`), `CHECKOUT_EVENT` (`voffice:checkout`) and `CONTACT_EVENT`
+  (`voffice:contact`) with their detail types. The stores hand them to `onEvent`; the components
+  dispatch them on `window`, and a site's own UI dispatches the same shapes. No detail carries
+  personal data.
+- `ENHANCE_PARTS` and `GATE_MARKERS`, exported from both entries: the markup contract of the
+  enhance engines and the markers the platform's page gates read.
+- `CHECKOUT_PARTS` gains `consent` and `insurancePremium`; `CHECKOUT_STRUCTURE` gains
+  `consents-before-submit` and `premium-before-submit`; `SUBMIT_WORDING` (per booking kind, German
+  and English) and `BOOKING_KIND_ATTRIBUTE` (`data-booking-kind` on the order button).
+
+### Copy templates
+
+- `fillTemplate(template, values)`: fills `{token}`s; an unknown token stays visible.
+- `Template<K>`: the type of a copy string whose tokens are `K`. `fillTemplate` needs a value for
+  every token a template declares and takes no other.
+- `defineCopy<T>()(overrides)`: checks a site's copy overrides at compile time (unknown keys, wrong
+  types, tokens the key does not declare) and returns them unchanged. `TokensOf` and
+  `CheckedCopy` are the types behind it.
+- The contact messages type their templates: `extraRequired` and `fieldInvalid` take `{label}`,
+  `messageTooLong` `{max}`, `sendFailed` `{email}`.
+
+### `./enhance`
+
+- `enhance(root, options)`: one call in the layout binds every engine below the root, idempotent,
+  returns a `Dispose`. Engines: `bindStrip`, `bindLayer`, `bindGallery`, `bindReveal`,
+  `bindClamp`, `bindShare`, `bindImageFade`, `bindFavorites`, and the MapLibre engines
+  (`createMapSurface`, `bindResultMarkers`, `bindPlaceMarkers`, `observeResultCardHover`). The
+  map engines take the `maplibre-gl` loader from the caller; the package does not depend on it.
+
+## Changed
+
+- **Peer dependency:** `@v-office/website-sdk >=2.25.0 <3` (was `>=2.13.0 <3`). 1.0.0 uses the
+  unavailable `code` (2.16), v9 `matchingPeriods` (2.22), `searchAllRentalsAtOnce` (2.23), the Hub
+  `/Setup` fix and `v9Reviews.criteria` (2.25).
+- **`createSdk(setup, mode?)`** takes an `SdkSetup` (was `createSdk(config, options?)`).
+  `SdkConfig` is the SDK's own config type, with `backend` explicit on v10.
+- **Every SDK runner takes the SDK first:** `fetchQuote(sdk, request)`,
+  `runLiveSearch(sdk, search, options)` (returns a `SearchPage`), `submitBooking(sdk, quote,
+contact, options)`, `payWithOption(sdk, option)`, `fetchInitialAvailability(sdk, input)`,
+  `fetchEndAvailability(sdk, input)`, `addQuoteService`, `removeQuoteService`,
+  `clearQuoteServices`, `selectQuotePolicy`, `selectQuoteInsurance`,
+  `pricePolicyBranches(sdk, base)`.
+- **`createCheckoutFlow(sdk, options)`:** `handover`, `returnPath` and `messages` are required;
+  the state is `phase`, `stay`, `services`, `policy`, `insurance`, `voucher`, `consents`,
+  `blockers` (why the order button is off), `submit`, `confirmation` and `payment`. New actions
+  `setDates`, `setParty`, `loadGuestCaps` (the arrival map's caps for the guest editor, loaded
+  when it opens), `selectPolicy`, `setConsent`, `retry`; `openInsuranceDocument(url)` and
+  `confirmInsuranceDocuments(confirmed)`; `pay(option)`. Events go to `onEvent`. The flow never
+  scrolls the window.
+- **Reshaped types:** `Stay` is `{ start, end, party }` in ISO days; `SearchResultItem` carries
+  `price: StayPrice`, `counts` and `periods`; `AlternativePeriod`, `FilterDef`, `ActiveFilter`
+  and `CheckoutIssue` are reshaped; `adaptGuestQuote` returns a `QuoteView` whose `price` is a
+  `PriceView`; `stayKeyOf` and `occupancyOf` take a `Stay` / `Party`;
+  `freeCancellationUntil(policy, arrival)` takes one policy and an `IsoDay`;
+  `detectCountry(countries, languages, fallback?)` no longer reads `navigator`.
+- **Dates** are `IsoDay` / `IsoMonth` strings at every public boundary.
+
+## Removed
+
+- **Site-specific defaults:** `CHECKOUT_RETURN_PATH`, `DEFAULT_RENTALS_PATH`,
+  `LiveSearchOptions.rentalsPath` and the German `SORT_OPTIONS` labels. Routes and copy are the
+  site's.
+- **0.1.x search, sort, filter and region helpers:** `SearchPayload`, `SearchImage`,
+  `SORT_PARAM`, `SortValue`, `SortOption`, `DEFAULT_SORT`, `activeSort`, `isPricedQuery`,
+  `isSortAvailable`, `resolveSdkSort`, `FilterType`, `isBooleanFilterActive`,
+  `activeFiltersFromQuery`, `PETS_PARAM`, `PETS_COUNT_PARAM`, `petsCountInQuery`,
+  `REGION_PARAM`, `activeRegions`, `scopeToRegions`.
+- **0.1.x date and price helpers:** `NIGHT_RANGE_ENABLED`, `NIGHT_RANGE_KEYS`,
+  `parseNightRange`, `parseParam`, `parseGermanParam`, `isoDate`, `stayParams`, `tidyPrice`,
+  `nightlyPrice`.
+- **0.1.x quote and checkout names:** `QuoteLine`, `PriceQuote`, `fullRefundRule`,
+  `policyFreeCancellationUntil`, `BookingContactForm`, `saveBookingSnapshot` and
+  `BookingSnapshotGuests` (`submitBooking` writes the snapshot), `VALIDATED_FIELDS`, `fieldError`,
+  `CheckoutFlowApi`, `CheckoutFlowState`, `CheckoutFlowActions`, `CheckoutFlowMessages`,
+  `BUTTON_SOLUTION_PATTERN`, `CountryGroupsLike`, and the checkout flow's `getSdk`, `stay`,
+  `chosenPolicy`, `filterOfferedPolicies` and `onRateConfigurationFault` options.
+- **`./enhance`:** `initImageCarousels`, `initRentalCarousel`, `initHistoryOverlay`,
+  `initGallery`, `HistoryOverlayOptions`, `GalleryOptions`, `GalleryLayer`, and the
+  `[data-rental-tabs]` / `.rental-track` selectors. Dots are repainted through `data-active`; no
+  Tailwind class is written.
+
+## Unchanged
+
+- Storage keys: `<namespace>-merkliste` (favourites), `voffice:checkout-context` and
+  `voffice:booking-return` (payment return). The `merkliste:changed` event.
+- Every URL key and the German sort values (`empfohlen`, `preis-auf`, `preis-ab`, `bewertung`,
+  `groesse`, `groesse-auf`, `gaeste`, `schlafzimmer`, `zufall`).
+- The gate markers on the same elements (`data-rental-stats`, `data-result-card`, `data-fav*`,
+  `data-img-*`, …), and legacy `.card-images` / `data-img-*` strips still bind.
+- `book()`, `pay()` and the contact `submit()` stay user-initiated only, and the § 7 VVG
+  insurance document gate is not configurable.
+- `describeSdkError` and `logSdkFailure`.
+- `fetchInitialAvailability` returns 0.2.0's `childrenAllowed` and `maxPets`. The `StayPicker`'s
+  `caps` carry them for the quote, and the checkout's `loadGuestCaps` for its guest editor, so
+  both bound the party by the v9 rules.

package/instructions/versions/1.0.0/MIGRATION.md

@@ -0,0 +1,252 @@
+# Migration: 0.2.0 to 1.0.0
+
+1.0.0 is not compatible with 0.x. Do the steps in this order, in one change. A site that also
+renders `@v-office/website-components` moves it to 1.0.0 in the same change and follows that
+package's `MIGRATION.md` after this one. A site that has only copied kit code and never imported
+0.x follows the same steps: replace the kit's SDK seam, stores and helpers with the 1.0.0 names
+below. The README (in this package) has every option and default.
+
+## 1. Dependencies
+
+Pin exact versions and install, so the lockfile matches:
+
+```sh
+pnpm add --save-exact @v-office/website-headless@1.0.0 @v-office/website-sdk@2.28.1
+# with the components:
+pnpm add --save-exact @v-office/website-components@1.0.0
+# so the build reports the contact surface:
+pnpm add --save-exact @v-office/site-manifest@0.3.0
+```
+
+- Pin `@v-office/website-sdk` 2.28.1. From 2.28.0, v9 availability states the occupancy, children
+  and pets rules the guest selectors apply; never pin below the version a site already has. From
+  2.27.0, with site-manifest 0.3.0, the build reports the SDK it
+  constructed, and the platform keeps the website's public token and SDK options current. Construct
+  the SDK from one setup only (`createSdk` and `shareSdk` with the same `SdkSetup` count as one).
+  `sdkMode: "all-rentals-at-once"` beside it counts as a second SDK on the same token: the token
+  stays current, the stored SDK options are kept. A second setup with another token corrects neither.
+- The peer range is `@v-office/website-sdk >=2.25.0 <3`. 2.25.0 fixes the v9 Hub `/Setup` answer
+  without configured add-ons; delete a site's `fetch` patch for `/api/v1/Setup` in this change,
+  never earlier.
+- `maplibre-gl` is not a dependency of this package. A site that shows a map pins `maplibre-gl`
+  5.x itself.
+
+## 2. The SDK setup
+
+Write the SDK input once, in `src/data/sdk.ts`, and import it everywhere. Spell out every env
+name: Vite inlines only the `import.meta.env.NAME` it sees, so `import.meta.env` passed whole can
+arrive without them in a build.
+
+```ts
+import { sdkConfigFromEnv, type SdkSetup } from "@v-office/website-headless";
+
+export const SDK: SdkSetup = {
+  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 passed to the SDK before (translationOverrides,
+  // customAttributes, rentalHighlightPrioritization, …): the setup is serialized into every island.
+  options: {},
+};
+```
+
+- **The env.** `CMS_BACKEND` must be `v9` or `v10`; there is no default any more (kit code read an
+  unset value as v9). The token is `HUB_API_KEY` on v9 and `VOFFICE_LOCAL_DEV_ACCESS_TOKEN` on
+  v10. Set either `CMS_STAGE` (`development` or `production`, the platform's endpoints) or every
+  URL variable of the backend (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`), never both. Do not rename a variable: the
+  platform's builder reads `HUB_API_KEY`. A missing or conflicting variable fails the build with an
+  `SdkEnvError` that names the variables.
+- **Build time** (Astro frontmatter, loaders, scripts): one instance for every loader, disposed
+  after the last one.
+
+  ```ts
+  const sdk = createSdk(SDK);
+  try {
+    const rentals = await loadRentalCatalogue(sdk, { locale: "de-DE" });
+    // … every other loader takes the same sdk
+  } finally {
+    await sdk.dispose();
+  }
+  ```
+
+- **Browser:** `const shared = shareSdk(SDK)` (or `await loadSharedSdk(SDK)` where the only SDK use
+  is a submit), pass `shared.sdk` to the stores, call `shared.release()` when the UI goes. Every
+  surface given the same `SDK` shares one instance and one rate limit; a different setup is a
+  second instance with its own 1 request/second queue.
+- Replace `createSdk(config, options)` with `createSdk({ config, options })`, and every
+  `sdkConfigFor(…)` built per surface with the one `SDK` constant. Delete the site's own SDK
+  modules (a `voffice.ts`, a `backend.ts` / `backendKind()`, an SDK error helper).
+
+## 3. Site constants
+
+Write each decision once in `src/data/` and pass the same constant to every place that needs it:
+
+| constant          | type                                                        | what it decides                                                                                             |
+| ----------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `SDK`             | `SdkSetup`                                                  | the SDK input (step 2)                                                                                      |
+| `SEARCH_CONTRACT` | `SearchContract` (`backend`, `nightRangeSearch`, `aliases`) | how the search runs on this backend; `nightRangeSearch: false` where the v9 Hub answers the ± pair unpriced |
+| `GUESTS`          | `GuestOptions` (`limits`, `childAge`, `defaultAdults`)      | the party limits; `limits.pets` 0 = no dogs, 1 = a toggle, more = a stepper                                 |
+| `DAY_PRICES`      | `DayPrices` (`"rounded"`, `"exact"`, `"none"`)              | prices in calendar cells; a site with a no-price ruling sets `"none"`                                       |
+| `POLICY_CHOICE`   | `PolicyChoiceMode` (`"rental-page"`, `"checkout"`)          | where the cancellation rate is chosen, one value for quote and checkout                                     |
+| `BOOKABLE`        | `BookableFrom` (`from`, `noticeUntil?`, `contact?`)         | a site that is not bookable online before a date                                                            |
+| `ADDRESS`         | `RentalAddressMode`                                         | how much of the address is published; required, there is no default                                         |
+| `FAVORITES_KEY`   | `favoritesStorageKey(namespace)`                            | the Merkliste's storage key                                                                                 |
+
+`FAVORITES_KEY` must stay byte-identical to the key the site wrote before (`<namespace>-merkliste`).
+Write the site's exact namespace expression, its fallback included (for example
+`favoritesStorageKey(import.meta.env.PUBLIC_STORAGE_NS || "<the old fallback>")`), and compare the
+key a deployed page writes before and after. A changed key empties every guest's list, and nothing
+migrates it. `favoritesStorageKey` throws on an empty namespace.
+
+## 4. What replaces what
+
+| 0.x                                                                                                                           | 1.0.0                                                                                                                         |
+| ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `createSdk(config, options?)`                                                                                                 | `createSdk({ config, options }, mode?)`; browser `shareSdk` / `loadSharedSdk`                                                 |
+| `fetchQuote(rentalId, period, occupancy, sdk, locale, voucher?)`                                                              | `fetchQuote(sdk, { rentalId, period, occupancy, locale, voucher })`; a booking widget uses `createQuoteFlow`                  |
+| `fetchInitialAvailability(sdk, rentalId, from, through, locale)`, `fetchEndAvailability(…)`                                   | `fetchInitialAvailability(sdk, input)`, `fetchEndAvailability(sdk, input)`; a calendar uses `createStayPicker`                |
+| `submitBooking(quote, contact, sdk, returnPath?)`, `payWithOption(option, sdk)`                                               | `submitBooking(sdk, quote, contact, { returnPath, kind? })`, `payWithOption(sdk, option)`                                     |
+| `runLiveSearch(sdk, search, locale, cursor?, options)` → `SearchPayload`                                                      | `runLiveSearch(sdk, search, { locale, backend, rentalHref, … })` → `SearchPage`; a results page uses `createSearchStore`      |
+| `DEFAULT_RENTALS_PATH`, `rentalsPath`                                                                                         | `rentalHref`, a required route template such as `"/unterkuenfte/{slug}"`                                                      |
+| `CHECKOUT_RETURN_PATH`                                                                                                        | `returnPath`, required on `createCheckoutFlow` and `submitBooking`                                                            |
+| `SORT_PARAM`, `SortValue`, `SORT_OPTIONS`, `DEFAULT_SORT`, `activeSort`, `resolveSdkSort`, `isSortAvailable`, `isPricedQuery` | `SortKey`, `SORT_URL_VALUE`, `DEFAULT_SORT_OPTIONS`, `sortFromSearch`, `toSdkSort`, `sortResults`; labels are copy            |
+| `FilterType`, `FilterDef`, `activeFiltersFromQuery`, `isBooleanFilterActive`                                                  | `FilterSpec` + `resolveFilters(getFilters output, spec)`, `readSelection`, `writeSelection`, `activeFilters`, `withoutFilter` |
+| `PETS_PARAM`, `PETS_COUNT_PARAM`, `petsCountInQuery`                                                                          | `readParty`, `partyPairs` (`petsCount` on search pages, `pets` on rental and checkout pages)                                  |
+| `REGION_PARAM`, `activeRegions`, `scopeToRegions`                                                                             | `readSearch` / `writeSearch` (`SEARCH_PARAMS.region`) and the search store's scope                                            |
+| `parseNightRange`, `NIGHT_RANGE_*`, `parseParam`, `parseGermanParam`, `stayParams`                                            | `readSearch`, `writeSearch`, `searchHref` with `SEARCH_CONTRACT`; `stayQuery`, `checkoutHref` for rental links                |
+| `isoDate(Date)`                                                                                                               | `IsoDay` strings: `todayIso`, `addDays`, `nightsBetween`, `formatIsoDate`                                                     |
+| `tidyPrice`, `nightlyPrice`                                                                                                   | `formatPriceLabel(label, cents)`; no amount is recomputed, so there is no nightly price                                       |
+| `QuoteLine`, `PriceQuote`                                                                                                     | `PriceView`, `PriceLine` (`QuoteView.price`)                                                                                  |
+| `fullRefundRule`, `policyFreeCancellationUntil`, `freeCancellationUntil(policies, Date)`                                      | `freeCancellationUntil(policy, arrival)`, `describePolicyOffer`, `offeredPolicies`, `policyStance`                            |
+| `SearchImage`                                                                                                                 | `CardImage`                                                                                                                   |
+| `BookingContactForm`                                                                                                          | `BookingContact`                                                                                                              |
+| `saveBookingSnapshot`                                                                                                         | nothing: `submitBooking` writes it; the return page reads it with `readPaymentReturn`                                         |
+| `VALIDATED_FIELDS`, `fieldError(name, value, …)`                                                                              | `createGuestForm`; field rules `emailError`, `phoneError`, `postalcodeError`, `streetWarning`                                 |
+| `BUTTON_SOLUTION_PATTERN`                                                                                                     | `SUBMIT_WORDING` (per booking kind); `assertCheckoutStructure` checks it                                                      |
+| `CountryGroupsLike`, a site's country list                                                                                    | `countryOptions({ locale, featured })` at build time, `dialCode`, `detectCountry(countries, languages)`                       |
+| `CheckoutFlowState`, `CheckoutFlowActions`, `CheckoutFlowApi`, `CheckoutFlowMessages`                                         | `CheckoutState`, `CheckoutActions`, `CheckoutFlow`, `CheckoutMessages`                                                        |
+
+Types that kept their name changed shape: `Stay` is `{ start, end, party }` with `IsoDay` strings
+(`stayKeyOf` and `occupancyOf` take it and a `Party`); `SearchResultItem` has `price: StayPrice`,
+`counts` and `periods` instead of `priceLabel`, `pills`, `isNew` and the `guests` / `bedrooms` /
+`area` fields; `AlternativePeriod`, `ActiveFilter` and `CheckoutIssue` are reshaped. Let the type
+checker find every use.
+
+## 5. The checkout flow
+
+```ts
+// 0.1.x
+createCheckoutFlow({
+  rentalId,
+  getSdk,
+  stay,
+  chosenPolicy,
+  filterOfferedPolicies,
+  messages,
+  locale,
+  onRateConfigurationFault,
+});
+
+// 1.0.0
+const flow = createCheckoutFlow(shared.sdk, {
+  rentalId,
+  locale,
+  returnPath: "/buchen/bestaetigung", // the site's route
+  handover: readCheckoutHandover(location.search, { allowOption: false }),
+  messages, // the five sentences of CheckoutMessages
+  policyChoice: POLICY_CHOICE,
+  guests: GUESTS,
+  onEvent: (detail) => window.dispatchEvent(new CustomEvent(CHECKOUT_EVENT, { detail })),
+});
+flow.start();
+```
+
+- The stay comes from the handover and is edited in place (`setDates`, `setParty`); the rate rule
+  is internal (`selectPolicy` with `policyChoice: "checkout"`).
+- Call `loadGuestCaps()` when your guest editor opens. `state.bounds` then follow the rental's
+  availability caps and, on v9, its children and pets rules, as 0.2.0's guest selector did.
+- Disable the order button while `state.blockers` is not empty and name the first blocker;
+  `submit` replaces `bookState`, `payment` replaces `payBusyKey` / `payError`.
+- `pay(option)` takes the option only. `openInsuranceDocument(url)` and
+  `confirmInsuranceDocuments(confirmed)` replace `openInsuranceDoc` and
+  `confirmInsuranceDocs(productKey, confirmed)`; `clearIssue` and `update` are gone.
+- The flow does not scroll: scroll to the confirmation when `phase.kind` becomes `"booked"`.
+- Run `assertCheckoutStructure` on the rendered checkout in a test. A custom checkout renders
+  `CHECKOUT_PARTS` (now with `checkout-consent` and `checkout-insurance-premium`) and
+  `BOOKING_KIND_ATTRIBUTE` on the order button.
+
+## 6. Enhancement: one `enhance()` call
+
+Remove every `initImageCarousels`, `initRentalCarousel`, `initGallery` and `initHistoryOverlay`
+call (and per-section init scripts). Call `enhance` once, in the layout:
+
+```ts
+import { enhance } from "@v-office/website-headless/enhance";
+import { FAVORITES_KEY } from "../data/favorites";
+
+// 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());
+```
+
+- Without ClientRouter, call `enhance(document, { favorites: { storageKey: FAVORITES_KEY } })`
+  once after the page loads. Favourites are bound only with a `storageKey`.
+- Markup binds through `data-part` values (`ENHANCE_PARTS`: `strip`, `strip-track`, `layer`,
+  `reveal`, `clamp`, `share`, `favorite`, `rental-gallery`, …). Legacy `.card-images` strips with
+  `data-img-*`, `[data-share]` and `[data-fav]` markup still bind; `[data-rental-tabs]` and
+  `.rental-track` do not, so move those to `data-part="strip"` markup. A layer is a `<dialog
+data-part="layer">` with an id.
+- The engines write state attributes (`data-active`, `data-state`), never Tailwind classes. Site
+  CSS that keyed on a class an init function added keys on the attribute now.
+
+## 7. Events
+
+- `onRateConfigurationFault` is gone. Pass `onEvent` to `createQuoteFlow` and
+  `createCheckoutFlow`; with the components, listen on `window` for `voffice:quote`,
+  `voffice:checkout` and `voffice:contact` (`detail.type`, no personal data).
+- The kits' window globals (`__searchStore`, `__favoritesMode`, `__offersMode`,
+  `__coordsByRentalId`, `__slideLoader`, …) are gone. A script that read one goes silent without an
+  error: move it to the store it needs or to a `voffice:*` event.
+- `merkliste:changed` (`{ id, saved }`) is unchanged.
+
+## 8. Delete
+
+- The site's SDK seam and its `fetch` patch for the Hub `/Setup` answer (step 1 and 2).
+- Copied kit stores, state machines and helpers that the names in step 4 replace: search, sort,
+  filters, regions, dates, prices, quote, checkout, validation, countries, favourites, carousel,
+  gallery and overlay code.
+- Route and copy constants the package no longer provides (`CHECKOUT_RETURN_PATH`, German sort
+  labels): routes go into the site's props, copy into the UI.
+
+## 9. Check
+
+Run the site's tests, `astro check` (0 errors) and a build. Never press the final booking, payment
+or contact submit against a real PMS to test: they create a real reservation, start a real payment
+and send a real request.
+
+## What stays the same
+
+- Storage keys: `<namespace>-merkliste`, `voffice:checkout-context`, `voffice:booking-return`.
+- Every URL key (`start`, `end`, `adults`, `children`, `childrenAges`, `petsCount`, `pets`,
+  `region`, `sort`, `policy`, `kind`, `offer`, …) and the German sort values (`empfohlen`,
+  `preis-auf`, …), so existing links, bookmarks and mails keep working.
+- The gate markers (`data-rental-stats`, `data-result-card`, `data-fav*`, `data-img-*`, …) on the
+  same elements.
+- `book()`, `pay()` and the contact `submit()` stay user-initiated only; the § 7 VVG insurance
+  document gate cannot be switched off.
+- `describeSdkError` and `logSdkFailure`.

package/instructions/versions/1.0.0/release.json

@@ -0,0 +1,10 @@
+{
+  "componentsAffectedByHeadlessChange": [
+    "searchBar",
+    "showcase",
+    "searchResults",
+    "quote",
+    "booking",
+    "contact"
+  ]
+}