includio-cms 0.37.1 → 0.37.3

package/API.md

@@ -1,8 +1,8 @@
-# includio-cms — Public API v0.37.1
+# includio-cms — Public API v0.37.3
 
 > Auto-generated by `scripts/generate-api-md.ts`. Do not edit by hand.
 
-Entry points: **23** · Stable: **665** · Experimental: **4**
+Entry points: **23** · Stable: **715** · Experimental: **4**
 
 Tags:
 - `@public` — frozen for v1.0; semver-protected.
@@ -13,17 +13,59 @@ Tags:
 
 ### `includio-cms`
 
+- `article(input: ArticleInput): JsonLdNode`
+- `interface ArticleInput`
+- `blogPosting(input: ArticleInput): JsonLdNode`
+- `breadcrumbList(items: Array<{ name: string; url: string }>): JsonLdNode`
 - `interface EmailAdapter` — Contract for email adapters. Used by `better-auth` reset-password flow and form submission
+- `faqPage(items: Array<{ question: string; answer: string }>): JsonLdNode`
+- `interface GeoInput`
+- `imageNode(img: string | MediaFile): string | JsonLdNode` — Normalize an image to a URL string or an ImageObject with dimensions.
+- `jsonLdGraph(nodes: JsonLdNode | JsonLdNode[]): { '@context': 'https://schema.org'; '@graph': JsonLdNode[]; }` — Wrap node(s) into a schema.org
+- `type JsonLdNode = Record<string, unknown> & { '@type': string | string[] }`
+- `localBusiness(input: LocalBusinessInput): JsonLdNode`
+- `interface LocalBusinessInput`
+- `organization(input: OrganizationInput): JsonLdNode`
+- `interface OrganizationInput`
+- `interface PostalAddressInput`
+- `pruneEmpty(value: T): T` — Recursively drop undefined/null/'' and empty arrays/objects.
 - `type ResolvedSeo = { [K in keyof SeoFieldData]: K extends 'ogImage' ? string | MediaFile | undefined : string | unde...` — Normalized SEO data — localized values flattened by `language`. A stable
 - `resolveSeo(entry: { seo?: Record<string, unknown> } | Record<string,..., language?: string): ResolvedSeo` — Resolve `entry.seo` into flat fields, flattening localized objects by
 - `interface SendMailOptions`
+- `slugifyFilename(base: string): string` — Slugify a media file base name (extension handled by the caller).
+- `thing(type: string | string[], props: Record<string, unknown> = {}): JsonLdNode` — Build a schema.org node of `type` from `props`, pruning empty values.
+- `webPage(input: WebPageInput): JsonLdNode`
+- `interface WebPageInput`
+- `website(input: WebSiteInput): JsonLdNode`
+- `interface WebSiteInput`
 
 ### `includio-cms/core`
 
+- `article(input: ArticleInput): JsonLdNode`
+- `interface ArticleInput`
+- `blogPosting(input: ArticleInput): JsonLdNode`
+- `breadcrumbList(items: Array<{ name: string; url: string }>): JsonLdNode`
 - `interface EmailAdapter` — Contract for email adapters. Used by `better-auth` reset-password flow and form submission
+- `faqPage(items: Array<{ question: string; answer: string }>): JsonLdNode`
+- `interface GeoInput`
+- `imageNode(img: string | MediaFile): string | JsonLdNode` — Normalize an image to a URL string or an ImageObject with dimensions.
+- `jsonLdGraph(nodes: JsonLdNode | JsonLdNode[]): { '@context': 'https://schema.org'; '@graph': JsonLdNode[]; }` — Wrap node(s) into a schema.org
+- `type JsonLdNode = Record<string, unknown> & { '@type': string | string[] }`
+- `localBusiness(input: LocalBusinessInput): JsonLdNode`
+- `interface LocalBusinessInput`
+- `organization(input: OrganizationInput): JsonLdNode`
+- `interface OrganizationInput`
+- `interface PostalAddressInput`
+- `pruneEmpty(value: T): T` — Recursively drop undefined/null/'' and empty arrays/objects.
 - `type ResolvedSeo = { [K in keyof SeoFieldData]: K extends 'ogImage' ? string | MediaFile | undefined : string | unde...` — Normalized SEO data — localized values flattened by `language`. A stable
 - `resolveSeo(entry: { seo?: Record<string, unknown> } | Record<string,..., language?: string): ResolvedSeo` — Resolve `entry.seo` into flat fields, flattening localized objects by
 - `interface SendMailOptions`
+- `slugifyFilename(base: string): string` — Slugify a media file base name (extension handled by the caller).
+- `thing(type: string | string[], props: Record<string, unknown> = {}): JsonLdNode` — Build a schema.org node of `type` from `props`, pruning empty values.
+- `webPage(input: WebPageInput): JsonLdNode`
+- `interface WebPageInput`
+- `website(input: WebSiteInput): JsonLdNode`
+- `interface WebSiteInput`
 
 ### `includio-cms/core/server`
 
@@ -332,8 +374,10 @@ Tags:
 - `const Image: LegacyComponentType`
 - `isImageFieldData(media: MediaFieldData): media is ImageFieldData`
 - `isVideoFieldData(media: MediaFieldData): media is VideoFieldData`
+- `const JsonLd: LegacyComponentType`
 - `const Media: LegacyComponentType`
 - `const Preview: LegacyComponentType`
+- `const Seo: LegacyComponentType`
 - `setCustomFields(defs: Map<string, CustomFieldDefinition>): <inferred>`
 - `setPreferMp4(value: boolean): <inferred>`
 - `setRemotes(data: typeof remotes): <inferred>`
@@ -343,6 +387,8 @@ Tags:
 
 ### `includio-cms/sveltekit/server`
 
+- `buildRobots(options: RobotsOptions = {}): string` — Build a robots.txt document. Defaults to allow-all + optional sitemap link.
+- `buildSitemap(entries: SitemapEntry[]): string` — Build a sitemap.xml document from a list of URL entries.
 - `cmsLayoutLoad(event: RequestEvent): <inferred>` — Returns `cmsContext` from `event.locals` for use in a SvelteKit layout
 - `countEntries(opts: CountEntriesOptions): Promise<number>` — Count entries matching the same filters as `resolveEntries`, without
 - `type CountEntriesOptions = Omit< ResolveEntriesOptions, 'limit' | 'offset' | 'populate' | 'orderBy' | 'dataOrderBy' >`
@@ -365,7 +411,10 @@ Tags:
 - `resolveEntry(opts: ResolveEntryOptions): Promise<Entry | null>` — Fetch a single populated Entry.
 - `interface ResolveEntryOptions`
 - `type ResolveStatus = 'published' | 'draft' | 'scheduled'` — Status filter for `resolveEntry`/`resolveEntries`/`countEntries`.
+- `interface RobotsOptions`
+- `interface RobotsRule`
 - `sendMail(options: SendMailOptions): Promise<void>` — Send an email through the configured CMS email adapter. Thin convenience
+- `interface SitemapEntry`
 
 ### `includio-cms/db-postgres`
 
@@ -691,18 +740,19 @@ Tags:
 - `createBooking(input: CreateBookingInput, opts: { now?: Date; actor?: PriceActor } = {}): Promise<{ booking: typeof bookingsTable.$inferSelect; accessToken: string }>` — Create a booking (public self-serve or staff). Validates catalog capacity +
 - `createBookingHandler(): { POST: RequestHandler }` — Public self-serve booking creation. Mount at `POST /api/booking`.
 - `createDepositPayment(bookingId: string): Promise<{ redirectUrl: string | null; status: 'redirect' | 'manual' | 'error'...` — Create the deposit payment for a freshly-created booking: ask the first
-- `createInstallmentPayment(bookingId: string, amount: number): Promise<{ paymentLink: string | null }>` — Generate an installment/balance payment link for an arbitrary amount (staff or
+- `createInstallmentPayment(bookingId: string, opts: InstallmentPaymentOptions): Promise<{ paymentLink: string | null }>` — Generate an installment/balance payment link. Records a pending ledger row keyed
 - `createMaintenanceHandler(): { POST: RequestHandler }` — Secured external trigger for booking maintenance — the swap-in for the
 - `createPortalHandler(): { GET: RequestHandler; POST: RequestHandler }` — Self-service portal. Mount at `GET|POST /api/booking/portal/[token]`.
 - `createWebhookHandler(): { POST: RequestHandler }` — Payment-provider webhook. Mount at `POST /api/booking/webhook/[provider]`.
 - `editBooking(bookingId: string, changes: BookingEditChanges, opts: { actor: 'staff' | 'portal'; now?: Date }): Promise<typeof bookingsTable.$inferSelect>` — Edit a booking (staff or portal). Recomputes totals per-participant + derived
 - `getBookingDb(): <inferred>` — Returns the Drizzle handle, asserting the postgres adapter is in use.
 - `getBookingMaintenanceStatus(): { running: boolean; lastRun: Date | null }`
+- `interface InstallmentPaymentOptions`
 - `listBookingAdjustments(bookingId: string): Promise<BookingAdjustment[]>` — List all adjustments (active + voided) for a booking, newest first.
 - `pickEmailTemplate(kind: BookingEmailKind): string` — Template file name for a kind (1:1 — kept as a function for future indirection).
 - `portalAddTrips(token: string, additions: Array<{ tripRef: string; assignments: string[] }>): <inferred>` — Self-service dobieranie wycieczki: doczytaj obecny stan, scal z `additions`
 - `portalEdit(token: string, changes: BookingEditChanges): <inferred>` — Portal self-service edit (actor:'portal' guards). Throws → handler maps to 409/400.
-- `portalPay(token: string, amount: number): <inferred>` — Portal: create an installment/balance payment link.
+- `portalPay(token: string): <inferred>` — Portal: create a balance payment link. The amount is NOT taken from the request —
 - `portalUpdateParticipant(token: string, assignmentId: string, data: Record<string, unknown>): <inferred>` — Portal self-service: customer fills their own participant data. Verifies the
 - `portalView(token: string): <inferred>` — Portal view: booking + items + participants + ledger (no staff data).
 - `priceFromExistingRows(tx: BookingTx, bookingId: string, config: ResolvedBookingConfig): Promise<ParticipantPriceResult>` — Price a booking from its CURRENTLY persisted people/items/assignments (no

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to includio-cms are documented here.
 Generated from `src/lib/updates/` — do not edit manually.
 
+## 0.37.2 — 2026-07-16
+
+Powierzchnia SEO/AEO rdzenia — reużywalne helpery, które raz naprawione w rdzeniu działają u każdego klienta (wyszły z wdrożenia SEO u pod-zwrotnikami). W tym samym patchu domyka się też łatka bezpieczeństwa bookingu (kwota płatności).
+
+### Added
+- **Buildery JSON-LD (schema.org) w `includio-cms/core`.** Typowane, czyste funkcje: `organization`, `localBusiness`, `website`, `webPage`, `breadcrumbList`, `article`, `blogPosting`, `faqPage` + generyk `thing` i `jsonLdGraph`. Opt-in — nic nie emitują domyślnie. `undefined`/puste wartości wypadają z outputu, więc częściowe dane dają poprawny minimalny JSON-LD. Bespoke typy (np. `TouristTrip + Offer`, `Product`) składasz po stronie projektu przez `thing("TouristTrip", { ... })` — rdzeń zostaje generyczny.
+- **Komponent `<JsonLd>` w `includio-cms/sveltekit`.** Renderuje `<script type="application/ld+json">` w `<svelte:head>` (SSR), escapuje `<` → breakout ze `<script>` jest niemożliwy. Przyjmuje obiekt albo tablicę (np. wynik `jsonLdGraph`).
+- **`buildSitemap` / `buildRobots` w `includio-cms/sveltekit/server`.** Czyste buildery: `buildSitemap(entries)` → string `sitemap.xml` (URL-e XML-escaped, `lastmod` `Date`→ISO lub string, opcjonalne `changefreq`/`priority`), `buildRobots(options)` → `robots.txt` (domyślnie allow-all + link do sitemapy, konfigurowalne reguły). Projekt posiada route i wpina helper: `export const GET = async () => new Response(buildSitemap(entries), { headers: { "content-type": "application/xml" } });`.
+
+### Fixed
+- **Slugifikacja nazw plików mediów.** Upload i zmiana nazwy przepuszczają basename przez `slugifyFilename` (nowy helper w `includio-cms/core`): `"IMG-1234 (1).jpeg"` → `img-1234-1.jpeg`, polskie znaki transliterowane, spacje/wielkość/nawiasy usunięte. Tylko nowe pliki — istniejące URL-e w bazie nietknięte (bez migracji). Cap 200 znaków, path-traversal niemożliwy (slug nie zawiera `/` ani `.`).
+- **`<Seo>` dopełniony i wyeksportowany z `includio-cms/sveltekit`.** Wcześniej komponent istniał, ale nie był eksportowany (martwy). Bugfix: `og:url` i `og:type` używają `property=` zamiast `name=` (wymóg Open Graph). Nowe propsy: `ogType` (domyślnie `website`; `article` dokłada `article:published_time`/`modified_time`/`author`/`section`/`tag`), `noindex` (→ `<meta name="robots" content="noindex">`), `siteName` (→ `og:site_name`). `ogImage` typu `MediaFile` emituje `og:image:width`/`height`/`alt`.
+- **Typografia — łamanie sierot przyimkowych.** `fixOrphans` wstawia NBSP nie tylko po jednoliterowych spójnikach (`i/w/z/o/u/a/e`), ale też po krótkich przyimkach (`do na od po we za ze ku nad pod bez dla przy`). Lista konfigurowalna parametrem `words` + eksport `DEFAULT_ORPHAN_WORDS`. Domyślnie konserwatywnie (bez spójników typu `oraz/lub`), żeby nie NBSP-ować za dużo.
+- **Bezpieczeństwo (booking): kwota dopłaty przestaje pochodzić z żądania HTTP.** Domknięcie łuku 0.37.1 (cena szła z katalogu, ale kwota wpłaty — nie): `portalPay` podawał `amount` z ciała żądania prosto do `createInstallmentPayment`, bez konfrontacji z saldem — przeglądarka dyktowała kwotę (nadpłata do ręcznego zwrotu albo link na grosz). Bramka kwotowa oparta na aktorze (bliźniak bramki cenowej): `portal` NIE dyktuje (serwer obciąża `totals.balance`, fail-closed gdy brak salda), `staff` może. Portalowa wpłata zapisuje się teraz z `createdBy` aktora — nie zahardkodowanym `staff` (koniec kłamstwa w audycie).
+- **Booking: `ledger.balance` przestaje gubić rabaty.** `portalView` liczył `ledger` z `totals.gross` → `balance = gross − paid`, pomijając `discount`/`surcharge`/`manualDiscount`; portal pokazywał dwa różne salda i przycisk płatności brał gorzej policzone. Teraz `toPortalView` karmi `ledgerSummary` wartością netto (`netOf(totals)`), więc `ledger.balance === totals.balance`.
+
+### Breaking
+- **`createInstallmentPayment(bookingId, amount)` → `createInstallmentPayment(bookingId, { actor, amount? })`.** `actor: "portal" | "staff"` jest wymagany. Dla `portal` kwota jest ignorowana (serwer obciąża saldo); dla `staff` podajesz `amount`. `portalPay(token, amount)` → `portalPay(token)` (kwota nie jest już parametrem). Dotyczy tylko konsumentów wołających te funkcje bezpośrednio — ścieżka przez handler portalu/remote admina zaktualizowana w rdzeniu.
+
 ## 0.37.1 — 2026-07-14
 
 Dwie łatki cenowe w bookingu. (1) Cena rezerwacji przestaje pochodzić z żądania HTTP — do 0.37.0 publiczne endpointy przyjmowały `unitPrice` prosto z ciała żądania i nikt nie konfrontował go z katalogiem, więc wyprawę dało się zarezerwować za grosz. (2) Data wyceny zostaje zamrożona na rezerwacji — dotąd każde jej dotknięcie (edycja, ale też zaksięgowanie korekty) przeliczało reguły zależne od czasu wg DZISIEJSZEJ daty, przez co early-bird sprzed miesięcy cicho znikał i klient robił się winien pieniądze.

package/DOCS.md

@@ -1,4 +1,4 @@
-# Includio CMS Documentation (v0.37.1)
+# Includio CMS Documentation (v0.37.3)
 
 > This file is auto-generated from the docs site. For the latest version, update the package.
 

package/ROADMAP.md

@@ -40,6 +40,23 @@
 - [x] `[fix]` `[breaking]` `[P0]` **Data wyceny zamrożona na rezerwacji** (`bookings.priced_at`). Dotąd cena bazowa była zamrożona, ale data — nie: `editBooking` i `priceFromExistingRows` (ścieżka **korekt**) przeliczały reguły zależne od czasu wg `new Date()`. Obsługa księgowała dopłatę ustaloną telefonicznie tydzień przed wylotem → `daysUntil(anchor, now)` spadało poniżej progu → **early-bird sprzed miesięcy cicho znikał, a klient robił się winien pieniądze**. Bomba tykała sama, bez żadnej zmiany cennika. Rezerwacje sprzed 0.37.1: `priced_at = NULL` → fallback na `created_at` (zero migracji danych). Pełny snapshot **wartości** polityki (`pricing_snapshot`) zostaje w 0.38.0 §4.4 — wymaga świadomej zmiany cennika przez klientkę, więc da się ją uprzedzić.
 - [x] `[fix]` `[breaking]` `[P0]` **Cena rezerwacji przestaje pochodzić z żądania HTTP.** Do 0.37.0 trzy publiczne drogi wpuszczały `unitPrice` z ciała żądania i nikt nie konfrontował go z katalogiem (`create-handler.ts:37`, portalowe `add-trips`, portalowe `edit` → `editBooking`) — wyprawę dało się zarezerwować za grosz. Bramka stoi teraz w rdzeniu (`createBooking`/`editBooking`), oparta na aktorze: `public`/`portal` nie dyktują ceny (nowa pozycja → szew `resolvePrice` z katalogu, istniejąca → jej `unitPriceSnapshot`), `staff` nadal może korygować ręcznie. Domyślny aktor to `public`, więc przyszły publiczny endpoint jest bezpieczny bez pamiętania o niczym. Fail-closed: brak `resolvePrice` = odmowa wyceny.
 
+## 0.37.2 — SEO/AEO surface + kwota płatności
+
+> Domknięcie tego samego łuku co 0.37.1: **cena** przestała pochodzić z żądania HTTP, ale **kwota płatności** wciąż pochodzi.
+> Zgłoszone z pod-zwrotnikami (2026-07-14) — klient z rabatem pakietowym płacił w portalu za dużo. Konsument załatał się u siebie
+> (`totals.balance` zamiast `ledger.balance`), ale przyczyna siedzi w rdzeniu i każdy kolejny konsument wdepnie w to samo.
+
+- [x] `[fix]` `[P0]` **Kwota dopłaty przestaje pochodzić z żądania HTTP.** `portalPay(token, amount)` podaje `amount` prosto do `createInstallmentPayment(bookingId, amount)` (`payments.ts:149`), a ta wkłada go do `totalGross` adaptera i insertuje `booking_payments` — **bez żadnej konfrontacji z `totals.balance`**. Przeglądarka dyktuje, ile zapłaci: może za dużo (nadpłata do zwrotu ręcznego), może grosz (link płatności na 0,01 zł). Bramka z 0.37.1 stanęła na `unitPrice`, ale nie na kwocie wpłaty. Fix: kwotę wyznacza/weryfikuje serwer względem `totals.balance` (aktor `portal` nie dyktuje kwoty, `staff` może — symetrycznie do bramki cenowej), fail-closed przy rozjeździe. Przy okazji: portalowa wpłata zapisuje się z `createdBy: 'staff'` (`payments.ts:187`), co kłamie w audycie. <!-- files: src/lib/booking/server/portal.ts, src/lib/booking/server/payments.ts -->
+- [x] `[fix]` `[P0]` **`ledger.balance` gubi rabaty — i kusi nazwą.** `portalView` woła `ledgerSummary(booking.totals.gross, payments)` (`server/portal.ts:48`), a `ledgerSummary` liczy `balance = gross - paid` (`ledger.ts:87`), z pominięciem `discount` / `surcharge` / `manualDiscount`. Autorytatywne jest `totals.balance` (`netOf(base) - paid`, `totals.ts:73`) i portalView zwraca je obok — więc widok podaje konsumentowi **dwa różne salda, a to gorzej policzone nosi bardziej oczywistą nazwę**. Efekt u konsumenta: portal pokazywał „Pozostało 532 zł" i „Do dopłaty 610 zł" na jednym ekranie, a przycisk płatności brał tę drugą. Fix: `ledgerSummary` liczy saldo z netto (albo `portalView` przestaje zwracać `ledger.balance` i zostawia sam `overpaid`). Test regresyjny: rezerwacja z rabatem → `ledger.balance === totals.balance`. <!-- files: src/lib/booking/ledger.ts, src/lib/booking/server/portal.ts, src/lib/booking/totals.ts -->
+
+> **SEO/AEO surface** (bundlowane w tym samym patchu, 2026-07-16). Reużywalne w rdzeniu — raz naprawione, działa u każdego klienta. Spec: `docs/superpowers/specs/2026-07-15-seo-aeo-core-surface-design.md`, plan: `docs/superpowers/plans/2026-07-16-seo-aeo-core-surface.md`.
+
+- [x] `[feature]` `[P1]` **Buildery JSON-LD + `<JsonLd>`** — typowane, czyste buildery schema.org w `includio-cms/core` (`organization`/`localBusiness`/`website`/`webPage`/`breadcrumbList`/`article`/`blogPosting`/`faqPage` + generyk `thing`/`jsonLdGraph`) i komponent `<JsonLd>` (SSR w `<svelte:head>`, escape `<`). Opt-in. <!-- files: src/lib/core/fields/jsonLd/, src/lib/sveltekit/components/json-ld.svelte -->
+- [x] `[fix]` `[P1]` **Slugifikacja nazw plików mediów** — `slugifyFilename` w core; `files-local` slugifikuje basename przy uploadzie/rename (tylko nowe pliki, non-breaking). <!-- files: src/lib/core/fields/slugifyFilename.ts, src/lib/files-local/index.ts -->
+- [x] `[fix]` `[P1]` **`<Seo>` dopełniony + wyeksportowany** — export z `sveltekit`; bugfix `og:url`/`og:type` `name→property`; `ogType`/`noindex`/`siteName`/`article` props; og:image width/height/alt z `MediaFile`. <!-- files: src/lib/sveltekit/components/seo.svelte, src/lib/sveltekit/index.ts -->
+- [x] `[fix]` `[P2]` **fixOrphans: przyimki wieloliterowe** — domyślny zestaw rozszerzony o 2–3-literowe przyimki, konfigurowalny `words` param + `DEFAULT_ORPHAN_WORDS`. <!-- files: src/lib/core/server/fields/utils/fixOrphans.ts -->
+- [x] `[feature]` `[P1]` **`buildSitemap`/`buildRobots`** — czyste buildery w `sveltekit/server`; projekt posiada route. <!-- files: src/lib/sveltekit/server/sitemap.ts -->
+
 ## 0.38.0 — Moduły: kontrakt vs polityka
 
 > **WSTRZYMANE (2026-07-14).** Łuk jest dojrzały, ale klientka nie zobaczy z niego nic, a produktyzacja
@@ -86,6 +103,7 @@ Spec: `docs/superpowers/specs/2026-07-13-moduly-kontrakt-vs-polityka-design.md`.
 
 ## Backlog
 
+- [ ] `[feature]` `[P2]` **Panel SEO w sidebarze admina (Yoast-like)** — osobny brainstorm/spec. Guided, niestechniczny panel (odwrotność przytłaczającego Yoasta, on-brand): globalna konfiguracja SEO, per-wpisowy box (snippet preview, noindex toggle, focus keyword → wtedy świadome rozszerzenie pola `seo`), pobranie sitemapy (nakładka na `buildSitemap`). **Przekierowania (redirects)** prawdopodobnie własny spec (tabela DB + hook 301/302 + CRUD). Szwy pod to = SEO surface 0.37.2.
 - [ ] `[fix]` `[P1]` Wyciek puli połączeń DB w dev (HMR) — pojedynczy proces `vite dev` konsumenta trzymał **100 połączeń** do Postgresa (cały `max_connections`), po czym baza odbijała wszystko: `FATAL: sorry, too many clients already` (zaobserwowane 2026-07-13 na pod-zwrotnikami). Hipoteza: każde przeładowanie modułu przez HMR tworzy nowy klient `postgres.js` (pula domyślnie 10), a stary nie jest zamykany — 10 przeładowań wyczerpuje limit. Sprawdzić zamykanie klienta w `import.meta.hot.dispose` / singleton na `globalThis` w adapterze. Dotyka każdego, kto dłużej pracuje w dev. <!-- files: src/lib/db-postgres/index.ts -->
 - [ ] `[chore]` `[P1]` CMS doctor — `validateLayout()` jest napisany i przetestowany, ale nie jest wołany z żadnego miejsca produkcyjnego: literówka w nazwie pola w tabie przechodzi po cichu (pole ląduje w orphanach). Podpiąć go do `defineConfig` obok `validatePreviews`, dołożyć `pnpm cms check` w CLI i zestaw reguł zdrowia configu (martwe pola, `pathTemplate` bez `previewUrl`/`previews`, itp.). <!-- files: src/lib/core/fields/layoutUtils.ts, src/lib/sveltekit/config.ts, src/lib/core/config/, src/lib/cli/index.ts -->
 - [ ] `[feature]` `[P2]` Date/datetime field — przebudowa na shadcn-svelte (bits-ui Calendar/DatePicker) zamiast natywnego inputu. Zgłoszone w QA Etap 5a (4/5); funkcjonalnie OK, odłożone jako osobny redesign pola daty. <!-- files: src/lib/admin/components/fields/date-field.svelte, datetime-field.svelte -->
@@ -99,6 +117,7 @@ Spec: `docs/superpowers/specs/2026-07-13-moduly-kontrakt-vs-polityka-design.md`.
 - [ ] `[feature]` `[P1]` Ban/unban UI — reason + expiry, `banUser`/`unbanUser` <!-- files: src/lib/admin/client/users/ban-user-dialog.svelte -->
 - [ ] `[feature]` `[P1]` Impersonation UI — impersonate/stop bar <!-- files: src/lib/admin/client/users/impersonation-bar.svelte -->
 - [ ] `[chore]` `[P2]` Caching/performance layer (scope TBD)
+  - [ ] `[perf]` Opt-out populacji media per-pole (`populate.fields` obejmujące media, nie tylko relacje) — dziś `resolveMediaFields` wołane bez `ctx`, galeria ciągnięta na marne w widokach list. Diagnoza + opcje: `docs/architecture/2026-07-16-media-populate-opt-out.md`
 - [ ] `[feature]` `[P2]` API/CLI for configuration (setup DX for less technical users)
 - [ ] `[feature]` `[P0]` Plugin hooks in CRUD ops (before/afterCreate, Update, Delete) <!-- files: src/lib/types/plugins.ts, src/lib/core/server/entries/operations/ -->
 - [ ] `[feature]` `[P0]` Plugin registration API — public surface for external plugins

package/dist/admin/remote/booking.remote.js

@@ -209,7 +209,7 @@ export const editBookingStaff = command(z.object({ bookingId: z.string().uuid(),
 /** Staff: generate an installment/balance payment link for any amount. @public */
 export const addPaymentLink = command(z.object({ bookingId: z.string().uuid(), amount: z.number().int().positive() }), async ({ bookingId, amount }) => {
     requireAuth();
-    const result = await createInstallmentPayment(bookingId, amount);
+    const result = await createInstallmentPayment(bookingId, { actor: 'staff', amount });
     if (result.paymentLink) {
         await sendBookingEmail(bookingId, 'payment-link', {
             amount,

package/dist/booking/payment-amount.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Pure amount gate for installment/balance payment links — the payment-side twin
+ * of the 0.37.1 price gate. Keeps the *amount* from being dictated by an untrusted
+ * HTTP request. All amounts are in **minor units** (grosze).
+ */
+export type PaymentActor = 'portal' | 'staff';
+/** Thrown when a requested payment amount is not allowed for the actor. */
+export declare class PaymentAmountError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve the amount to charge on an installment/balance link.
+ *
+ * - `portal` (untrusted): the server dictates the amount = current outstanding
+ *   `balance`; any `requestedAmount` from the browser is ignored. Fail-closed
+ *   when nothing is due (`balance <= 0`).
+ * - `staff` (trusted): honors `requestedAmount` (positive integer minor units) —
+ *   staff may bill a custom amount, e.g. a partial installment or a prepayment.
+ *
+ * @throws {PaymentAmountError} portal with nothing due, or staff with a
+ *   non-positive / fractional / missing amount.
+ */
+export declare function resolveInstallmentAmount(balance: number, actor: PaymentActor, requestedAmount?: number): number;

package/dist/booking/payment-amount.js

@@ -0,0 +1,37 @@
+/**
+ * Pure amount gate for installment/balance payment links — the payment-side twin
+ * of the 0.37.1 price gate. Keeps the *amount* from being dictated by an untrusted
+ * HTTP request. All amounts are in **minor units** (grosze).
+ */
+/** Thrown when a requested payment amount is not allowed for the actor. */
+export class PaymentAmountError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PaymentAmountError';
+    }
+}
+/**
+ * Resolve the amount to charge on an installment/balance link.
+ *
+ * - `portal` (untrusted): the server dictates the amount = current outstanding
+ *   `balance`; any `requestedAmount` from the browser is ignored. Fail-closed
+ *   when nothing is due (`balance <= 0`).
+ * - `staff` (trusted): honors `requestedAmount` (positive integer minor units) —
+ *   staff may bill a custom amount, e.g. a partial installment or a prepayment.
+ *
+ * @throws {PaymentAmountError} portal with nothing due, or staff with a
+ *   non-positive / fractional / missing amount.
+ */
+export function resolveInstallmentAmount(balance, actor, requestedAmount) {
+    if (actor === 'staff') {
+        if (!Number.isInteger(requestedAmount) || requestedAmount <= 0) {
+            throw new PaymentAmountError('Kwota wpłaty musi być dodatnią liczbą całkowitą (grosze).');
+        }
+        return requestedAmount;
+    }
+    // portal: browser does not dictate the amount — the server charges the balance.
+    if (balance <= 0) {
+        throw new PaymentAmountError('Brak salda do zapłaty.');
+    }
+    return balance;
+}

package/dist/booking/server/http/portal-handler.js

@@ -65,7 +65,8 @@ export function createPortalHandler() {
             }
             try {
                 if (action === 'pay') {
-                    const out = await portalPay(token, Number(body.amount) || 0);
+                    // Kwota NIE pochodzi z żądania — serwer obciąża saldo (bramka kwotowa w rdzeniu).
+                    const out = await portalPay(token);
                     return out ? json(out) : json({ error: 'Not found' }, { status: 404 });
                 }
                 if (action === 'edit') {

package/dist/booking/server/payments.d.ts

@@ -1,5 +1,6 @@
 import type { PaymentEvent } from '../../shop/types.js';
 import type { PaymentKind } from '../ledger.js';
+import { type PaymentActor } from '../payment-amount.js';
 /**
  * Create the deposit payment for a freshly-created booking: ask the first
  * configured adapter for a payment (charging only the deposit amount via an
@@ -22,12 +23,21 @@ export declare function applyWebhookPayment(event: PaymentEvent): Promise<{
     bookingId: string | null;
     kind: PaymentKind | null;
 }>;
+export interface InstallmentPaymentOptions {
+    /** Trust level of the caller. `portal` cannot dictate the amount; `staff` can. */
+    actor: PaymentActor;
+    /** Required for `staff` (positive minor units). Ignored for `portal` (server charges the balance). */
+    amount?: number;
+}
 /**
- * Generate an installment/balance payment link for an arbitrary amount (staff or
- * portal). Records a pending ledger row keyed by the provider ref; the webhook
- * settles it later.
+ * Generate an installment/balance payment link. Records a pending ledger row keyed
+ * by the provider ref; the webhook settles it later.
+ *
+ * The charged amount is gated by {@link resolveInstallmentAmount}: for `actor:'portal'`
+ * the browser cannot dictate it — the server charges the outstanding `totals.balance`
+ * (fail-closed when nothing is due); `actor:'staff'` may bill a custom `amount`.
  */
-export declare function createInstallmentPayment(bookingId: string, amount: number): Promise<{
+export declare function createInstallmentPayment(bookingId: string, opts: InstallmentPaymentOptions): Promise<{
     paymentLink: string | null;
 }>;
 /** Record a manual cash payment (staff). Settles immediately and recomputes status. */

package/dist/booking/server/payments.js

@@ -6,6 +6,7 @@ import { applyPaymentEvent } from '../webhook-logic.js';
 import { deriveStatus } from '../state-machine.js';
 import { netOf } from '../totals.js';
 import { buildPaymentContext } from '../payment-context.js';
+import { resolveInstallmentAmount } from '../payment-amount.js';
 /**
  * Create the deposit payment for a freshly-created booking: ask the first
  * configured adapter for a payment (charging only the deposit amount via an
@@ -127,11 +128,14 @@ export async function applyWebhookPayment(event) {
     });
 }
 /**
- * Generate an installment/balance payment link for an arbitrary amount (staff or
- * portal). Records a pending ledger row keyed by the provider ref; the webhook
- * settles it later.
+ * Generate an installment/balance payment link. Records a pending ledger row keyed
+ * by the provider ref; the webhook settles it later.
+ *
+ * The charged amount is gated by {@link resolveInstallmentAmount}: for `actor:'portal'`
+ * the browser cannot dictate it — the server charges the outstanding `totals.balance`
+ * (fail-closed when nothing is due); `actor:'staff'` may bill a custom `amount`.
  */
-export async function createInstallmentPayment(bookingId, amount) {
+export async function createInstallmentPayment(bookingId, opts) {
     const config = requireBookingConfig();
     const db = getBookingDb();
     const [booking] = await db.select().from(bookingsTable).where(eq(bookingsTable.id, bookingId));
@@ -140,6 +144,8 @@ export async function createInstallmentPayment(bookingId, amount) {
     const adapter = config.payment[0];
     if (!adapter)
         throw new Error('No payment adapter configured');
+    // Amount gate (payment-side twin of the 0.37.1 price gate).
+    const amount = resolveInstallmentAmount(booking.totals.balance, opts.actor, opts.amount);
     const ctx = {
         ...buildPaymentContext({
             accessToken: booking.accessToken,
@@ -165,7 +171,7 @@ export async function createInstallmentPayment(bookingId, amount) {
         status: 'pending',
         providerRef: result.providerRef ?? null,
         paymentLink: result.redirectUrl ?? null,
-        createdBy: 'staff'
+        createdBy: opts.actor
     });
     return { paymentLink: result.redirectUrl ?? null };
 }

package/dist/booking/server/portal.d.ts

@@ -123,8 +123,11 @@ export declare function portalEdit(token: string, changes: BookingEditChanges):
     }[];
     ledger: import("../ledger.js").LedgerSummary;
 } | null>;
-/** Portal: create an installment/balance payment link. */
-export declare function portalPay(token: string, amount: number): Promise<{
+/**
+ * Portal: create a balance payment link. The amount is NOT taken from the request —
+ * the server charges the outstanding `totals.balance` (see {@link createInstallmentPayment}).
+ */
+export declare function portalPay(token: string): Promise<{
     paymentLink: string | null;
 } | null>;
 /**

package/dist/booking/server/portal.js

@@ -2,6 +2,7 @@ import { and, eq, inArray, isNull } from 'drizzle-orm';
 import { getBookingDb } from './db.js';
 import { bookingsTable, bookingItemsTable, bookingPersonsTable, bookingItemPersonsTable, bookingPaymentsTable } from '../../db-postgres/schema/booking/index.js';
 import { ledgerSummary } from '../ledger.js';
+import { netOf } from '../totals.js';
 import { editBooking } from './bookings.js';
 import { createInstallmentPayment } from './payments.js';
 import { resolveItemSchema, saveParticipantData } from './participants.js';
@@ -29,7 +30,9 @@ export function toPortalView(booking, items, participants, payments, schemaByIte
             kind: p.kind,
             paidAt: p.paidAt ?? null
         })),
-        ledger: ledgerSummary(booking.totals.gross, payments)
+        // Ledger balance must fold in discounts/surcharges — feed NET (like `totals.balance`),
+        // not the pre-discount `gross`, so `ledger.balance === totals.balance`.
+        ledger: ledgerSummary(netOf(booking.totals), payments)
     };
 }
 /** Resolve a booking by its unguessable portal access token (active only). */
@@ -138,12 +141,15 @@ export async function portalEdit(token, changes) {
     await editBooking(booking.id, changes, { actor: 'portal' });
     return portalView(token);
 }
-/** Portal: create an installment/balance payment link. */
-export async function portalPay(token, amount) {
+/**
+ * Portal: create a balance payment link. The amount is NOT taken from the request —
+ * the server charges the outstanding `totals.balance` (see {@link createInstallmentPayment}).
+ */
+export async function portalPay(token) {
     const booking = await resolveByToken(token);
     if (!booking)
         return null;
-    return createInstallmentPayment(booking.id, amount);
+    return createInstallmentPayment(booking.id, { actor: 'portal' });
 }
 /**
  * Portal self-service: customer fills their own participant data. Verifies the

package/dist/components/ui/input-group/input-group-input.svelte.d.ts

@@ -2,7 +2,7 @@ declare const InputGroupInput: import("svelte").Component<(Omit<import("svelte/e
     type: "file";
     files?: FileList;
 } | {
-    type?: "number" | "image" | "url" | "text" | "date" | "search" | "radio" | "hidden" | "email" | "password" | (string & {}) | "reset" | "color" | "button" | "checkbox" | "tel" | "time" | "month" | "submit" | "datetime-local" | "range" | "week";
+    type?: "number" | "image" | "url" | "text" | "date" | "search" | "radio" | "email" | "hidden" | "password" | (string & {}) | "reset" | "color" | "button" | "checkbox" | "tel" | "time" | "month" | "submit" | "datetime-local" | "range" | "week";
     files?: undefined;
 })) & {
     ref?: HTMLElement | null | undefined;

package/dist/components/ui/sidebar/sidebar-input.svelte.d.ts

@@ -2,7 +2,7 @@ declare const SidebarInput: import("svelte").Component<(Omit<import("svelte/elem
     type: "file";
     files?: FileList;
 } | {
-    type?: "number" | "image" | "url" | "text" | "date" | "search" | "radio" | "hidden" | "email" | "password" | (string & {}) | "reset" | "color" | "button" | "checkbox" | "tel" | "time" | "month" | "submit" | "datetime-local" | "range" | "week";
+    type?: "number" | "image" | "url" | "text" | "date" | "search" | "radio" | "email" | "hidden" | "password" | (string & {}) | "reset" | "color" | "button" | "checkbox" | "tel" | "time" | "month" | "submit" | "datetime-local" | "range" | "week";
     files?: undefined;
 })) & {
     ref?: HTMLElement | null | undefined;

package/dist/core/cms.d.ts

@@ -2,9 +2,10 @@ import type { DatabaseAdapter } from '../types/adapters/db.js';
 import type { FilesAdapter } from '../types/adapters/files.js';
 import type { AdminConfig, ApiKeyConfig, AuthConfig, CMSConfig, ICMS, MediaConfig, TypographyConfig } from '../types/cms.js';
 import type { CollectionConfigWithType } from '../types/collections.js';
-import type { Language } from '../types/languages.js';
+import { type Language } from '../types/languages.js';
 import type { SingleConfigWithType } from '../types/singles.js';
 import type { CustomFieldDefinition, IconSetPlugin, Plugin } from '../types/plugins.js';
+import { type LocaleUrl } from './i18n/localeUrl.js';
 import type { FormConfig } from '../types/forms.js';
 import type { AIAdapter } from '../types/adapters/ai.js';
 import type { EmailAdapter, SendMailOptions } from '../types/adapters/email.js';
@@ -24,6 +25,8 @@ export declare class CMS implements ICMS {
     singles: Record<string, SingleConfigWithType>;
     forms: Record<string, FormConfig>;
     languages: Language[];
+    /** Znormalizowana mapa locale→URL (prefiks/host, default). Jeden punkt prawdy i18n. */
+    localeUrl: LocaleUrl;
     mediaConfig: MediaConfig;
     typographyConfig: TypographyConfig;
     sidebarHelp: boolean;

package/dist/core/cms.js

@@ -1,5 +1,7 @@
+import { languageCode } from '../types/languages.js';
 import { isIconSetPlugin } from '../types/plugins.js';
 import { setSchemaGetCMS } from './fields/fieldSchemaToTs.js';
+import { buildLocaleUrl } from './i18n/localeUrl.js';
 import { betterAuth } from 'better-auth';
 import { drizzleAdapter } from 'better-auth/adapters/drizzle';
 import { admin } from 'better-auth/plugins';
@@ -17,6 +19,8 @@ export class CMS {
     singles;
     forms;
     languages;
+    /** Znormalizowana mapa locale→URL (prefiks/host, default). Jeden punkt prawdy i18n. */
+    localeUrl;
     mediaConfig;
     typographyConfig;
     sidebarHelp;
@@ -67,10 +71,13 @@ export class CMS {
                 ...form
             };
         });
-        this.languages = config.languages || [];
-        if (this.languages.length === 0) {
+        const rawLanguages = config.languages || [];
+        if (rawLanguages.length === 0) {
             throw new Error('CMS config must include at least one language.');
         }
+        // `languages` znormalizowane do kodów (reszta rdzenia zakłada string[]); url/default niesie localeUrl.
+        this.languages = rawLanguages.map(languageCode);
+        this.localeUrl = buildLocaleUrl(rawLanguages);
         this.apiKeys = config.apiKeys || [];
         if (config.plugins) {
             this.plugins = config.plugins;

package/dist/core/fields/jsonLd/builders.d.ts

@@ -0,0 +1,74 @@
+import type { MediaFile } from '../../../types/media.js';
+import { type JsonLdNode } from './graph.js';
+export interface OrganizationInput {
+    name: string;
+    url?: string;
+    logo?: string | MediaFile;
+    sameAs?: string[];
+    description?: string;
+}
+export declare function organization(input: OrganizationInput): JsonLdNode;
+export interface PostalAddressInput {
+    streetAddress?: string;
+    addressLocality?: string;
+    postalCode?: string;
+    addressRegion?: string;
+    addressCountry?: string;
+}
+export interface GeoInput {
+    latitude?: number;
+    longitude?: number;
+}
+export interface LocalBusinessInput extends OrganizationInput {
+    telephone?: string;
+    email?: string;
+    image?: string | MediaFile;
+    address?: PostalAddressInput;
+    geo?: GeoInput;
+    openingHours?: string | string[];
+    priceRange?: string;
+}
+export declare function localBusiness(input: LocalBusinessInput): JsonLdNode;
+export interface WebSiteInput {
+    name: string;
+    url: string;
+    description?: string;
+    inLanguage?: string;
+    /** e.g. https://site/search?q={search_term_string} */
+    searchUrlTemplate?: string;
+}
+export declare function website(input: WebSiteInput): JsonLdNode;
+export interface WebPageInput {
+    name: string;
+    url: string;
+    description?: string;
+    inLanguage?: string;
+    isPartOf?: string;
+}
+export declare function webPage(input: WebPageInput): JsonLdNode;
+export declare function breadcrumbList(items: Array<{
+    name: string;
+    url: string;
+}>): JsonLdNode;
+export interface ArticleInput {
+    headline: string;
+    url?: string;
+    image?: string | MediaFile;
+    description?: string;
+    datePublished?: string;
+    dateModified?: string;
+    author?: string | {
+        name: string;
+        url?: string;
+    };
+    publisher?: OrganizationInput;
+    inLanguage?: string;
+    section?: string;
+    keywords?: string;
+}
+export declare function article(input: ArticleInput): JsonLdNode;
+export declare function blogPosting(input: ArticleInput): JsonLdNode;
+export declare function faqPage(items: Array<{
+    question: string;
+    answer: string;
+}>): JsonLdNode;