includio-cms 0.22.0 → 0.24.0

package/ROADMAP.md

@@ -5,344 +5,19 @@
 > `[P0]` critical | `[P1]` important | `[P2]` nice-to-have
 > `<!-- files: path/to/file.ts -->` optionally linked files
 >
-> **Versioning:** 0.0.69 is the last `0.0.x` release. From 0.1.0 onward: `0.MINOR.0` = features/changes, `0.MINOR.PATCH` = fixes.
-
-## 0.0.69 _(last 0.0.x)_
-
-- [x] `[feature]` `[P1]` DnD reordering in array fields + arrayMove utility <!-- files: src/cms/fields/array-field -->
-- [x] `[fix]` `[P1]` Nav-search: batch-fetch data before rendering Command dialog <!-- files: src/cms/nav-search -->
-
-## 0.1.0 — Stabilization
-
-- [x] `[fix]` `[P0]` Collection table pagination — server-side, persistent page state, archived tab <!-- files: src/lib/admin/client/collection/collection-entries.svelte, src/lib/admin/client/collection/table-pagination.svelte -->
-- [x] `[fix]` `[P0]` Language switcher — reactive globally without reload, remove hardcoded en/pl <!-- files: src/lib/admin/state/interface-language.svelte.ts, src/lib/admin/components/layout/header-actions.svelte -->
-- [x] `[fix]` `[P0]` User account section — fix name input, aria-pressed on prefs, clean up 2FA stub (email change deferred to 0.1.2, avatar upload skipped) <!-- files: src/lib/admin/client/account/ -->
-- [x] `[fix]` `[P0]` Media tag counts always 0 — pass actual files to TagSidebar <!-- files: src/lib/admin/components/media/media-library.svelte, src/lib/admin/components/media/tag-sidebar.svelte -->
-- [x] `[fix]` `[P0]` Hybrid target — don't render `data-hybrid-path` for non-logged-in users <!-- files: src/lib/sveltekit/components/hybrid-target.svelte -->
-
-## 0.1.1 — Input integrity
-
-- [x] `[fix]` `[P1]` Input constraints UI — HTML maxlength, character counter, pattern feedback <!-- files: src/lib/admin/components/fields/text-field.svelte, src/lib/admin/components/fields/text-field-wrapper.svelte -->
-- [x] `[fix]` `[P1]` Array field maxItems — disable Add button when max reached <!-- files: src/lib/admin/components/fields/array-field.svelte -->
-- [x] `[feature]` `[P1]` Array field fixed length — fixed item count, no add/remove, reorder only
-- [x] `[feature]` `[P1]` Field constraint info display — show constraints before validation error (WCAG/ATAG) <!-- files: src/lib/admin/components/fields/text-field-wrapper.svelte, src/lib/admin/components/fields/field-renderer.svelte -->
-
-## 0.1.2 — User management & RBAC
-
-### Phase 1 — Core
-
-- [x] `[feature]` `[P0]` RBAC middleware — `requireRole()`, role check w `requireAuth()` <!-- files: src/lib/admin/remote/middleware/auth.ts -->
-- [x] `[feature]` `[P0]` Admin users page — list, search, pagination via `authClient.admin.listUsers` <!-- files: src/lib/admin/client/users/ -->
-- [x] `[feature]` `[P0]` Create user — dialog z email/password/name/role via `authClient.admin.createUser` <!-- files: src/lib/admin/client/users/create-user-dialog.svelte -->
-- [x] `[feature]` `[P0]` Edit user — name, email, role via `adminUpdateUser` + `setRole` <!-- files: src/lib/admin/client/users/edit-user-dialog.svelte -->
-- [x] `[feature]` `[P0]` Delete user — confirmation dialog via `removeUser` <!-- files: src/lib/admin/client/users/ -->
-- [x] `[feature]` `[P0]` Route/sidebar gating — ukryj Users nav + chroń `/admin/users` dla non-admin <!-- files: src/lib/admin/components/layout/nav-main.svelte, src/lib/sveltekit/server/handle.ts -->
-- [x] `[feature]` `[P0]` First user bootstrap — pierwszy utworzony user auto-gets role `admin` <!-- files: src/lib/server/auth.ts -->
-
-### Phase 2 — Extended
-
-- [x] `[feature]` `[P1]` Admin session mgmt — list/revoke sesji innych userów <!-- files: src/lib/admin/client/users/user-sessions-sheet.svelte -->
-- [x] `[feature]` `[P2]` Email invitation system — invite link generation (custom, nie w better-auth) <!-- files: src/lib/admin/remote/invite.ts -->
-
-## 0.1.3 — Admin DX
-
-- [x] `[feature]` `[P1]` Admin route scaffolding — CLI `includio scaffold admin`, catch-all API handler, page.params fallbacks for CollectionPage/EntryPage <!-- files: src/lib/cli/scaffold/admin.ts, src/lib/admin/api/handler.ts, src/lib/admin/client/collection/collection-page.svelte, src/lib/admin/client/entry/entry-page.svelte -->
-
-## 0.1.4 — Build & reactivity fixes
-
-- [x] `[fix]` `[P0]` Prepack: remove dist/paraglide/.gitignore before publint (publish validation) <!-- files: package.json -->
-- [x] `[fix]` `[P1]` Collection entries: {#key} wrapper on query blocks to force re-fetch on param change <!-- files: src/lib/admin/client/collection/collection-entries.svelte -->
-
-## 0.2.1–0.5.0 — Hybrid Editor System
-
-> Szczegóły w **[ROADMAP-EDITOR.md](./ROADMAP-EDITOR.md)**
-
-- **0.2.1** — array→blocks rename + simple array `[breaking]`
-- **0.2.2** — Structured Content field (TipTap JSON output)
-- **0.3.0** — Bard-style inline blocks
-- **0.4.0** — Zone system (layout orchestration)
-- **0.4.1** — Accessibility layer (ATAG Part B)
-- **0.5.0** — Frontend rendering
-
-## 0.5.1 — Patches & dashboard
-
-- [x] `[feature]` `[P1]` Restore archived entries — banner, read-only mode, list actions
-- [x] `[feature]` `[P2]` Dashboard: changelog modal, orphaned entries redesign, grid layout
-- [x] `[fix]` `[P1]` Translation flow — reactive status, switcher UX, dynamic ref, copyFrom crash, panel scroll
-- [x] `[fix]` `[P1]` False "Niezapisane zmiany" on entry load
-- [x] `[fix]` `[P2]` Hide translation dots for non-required empty fields
-
-## 0.5.2 — Update system fix
-
-- [x] `[fix]` `[P1]` Split `migration` field into `sql` + `notes` — fixes CLI crash on text descriptions
-
-## 0.5.3 — Form fields, inline blocks, hybrid preview
-
-- [x] `[feature]` `[P1]` Form fields: select type, minLength/maxLength, errorMessage, remote commands
-- [x] `[feature]` `[P1]` Conditional field visibility (showWhen)
-- [x] `[feature]` `[P1]` Hybrid preview: device frames, container queries
-- [x] `[feature]` `[P2]` TipTap placeholder extension + Notion-style styles
-- [x] `[feature]` `[P1]` Server-side field resolution for inline blocks
-- [x] `[feature]` `[P1]` Inline blocks: standalone form, field rendering, collapse UI
-- [x] `[feature]` `[P2]` URL field: rel attribute, external auto-detect, UI redesign
-- [x] `[feature]` `[P2]` Switch UI component + boolean field toggle
-- [x] `[chore]` `[P2]` Storybook stories for all field types
-- [x] `[chore]` `[P1]` Field components refactor: bindable value props
-
-## 0.5.4 — Collection ordering & list columns
-
-- [x] `[feature]` `[P1]` Orderable collections: DnD reordering with keyboard alternative (WCAG 2.1) <!-- files: src/lib/admin/client/collection/data-table.svelte, src/lib/admin/client/collection/collection-entries.svelte -->
-- [x] `[feature]` `[P1]` Custom list columns: display entry fields as columns in collection list <!-- files: src/lib/admin/client/collection/collection-entries.svelte -->
-- [x] `[feature]` `[P1]` `sortOrder` column + `reorderEntriesCommand` remote <!-- files: src/lib/db-postgres/schema/entry.ts, src/lib/admin/remote/entry.remote.ts -->
-
-## 0.5.5 — REST API & orderable fixes
-
-- [x] `[feature]` `[P1]` REST API with API key authentication — CRUD for collections, singletons, entries, schema, languages <!-- files: src/lib/admin/api/rest/ -->
-- [x] `[feature]` `[P1]` API key configuration in CMS config (`apiKeys`) <!-- files: src/lib/types/cms.ts, src/lib/core/cms.ts -->
-- [x] `[feature]` `[P2]` getEntries `orderBy` parameter support <!-- files: src/lib/types/entries.ts, src/lib/core/server/entries/operations/get.ts -->
-- [x] `[fix]` `[P1]` Orderable collections: proper `<tr>` markup, visible reorder buttons, selection enabled <!-- files: src/lib/admin/client/collection/data-table.svelte -->
-- [x] `[fix]` `[P1]` Relation field respects orderable collection sort order <!-- files: src/lib/admin/components/fields/relation-field.svelte -->
-- [x] `[fix]` `[P1]` Nav active state exact match — prevents false highlights <!-- files: src/lib/admin/components/layout/nav-*.svelte -->
-- [x] `[chore]` `[P2]` Admin scaffold generates REST API route <!-- files: src/lib/cli/scaffold/admin.ts -->
-
-## 0.5.6 — Relation field & collection improvements
-
-- [x] `[feature]` `[P1]` Relation field: dialog picker, reorder, search, multi-select UX <!-- files: src/lib/admin/components/fields/relation-field.svelte -->
-- [x] `[feature]` `[P1]` getEntryLabels — lightweight labels endpoint for relation fields <!-- files: src/lib/admin/remote/entry.remote.ts -->
-- [x] `[feature]` `[P2]` Collection list: relation labels in columns, delete only for archived <!-- files: src/lib/admin/client/collection/collection-entries.svelte -->
-- [x] `[feature]` `[P2]` Icon map — string-based sidebar icons replace component refs <!-- files: src/lib/admin/components/layout/nav-main.svelte -->
-- [x] `[fix]` `[P1]` TipTap: auto-expand new inline blocks, editor overflow, toolbar bg <!-- files: src/lib/admin/components/fields/structured-content/ -->
-- [x] `[chore]` `[P2]` Runtime types: FormEntryMap rename, add remote.ts
-- [x] `[chore]` `[P2]` Remove mode-watcher, hardcode light theme
-
-## 0.5.7 — SEO field & content fixes
-
-- [x] `[feature]` `[P1]` SEO field: auto/manual slug toggle with Switch <!-- files: src/lib/admin/components/fields/seo-field.svelte -->
-- [x] `[fix]` `[P1]` Structured content: skip empty paragraphs, wrap inline blocks in div <!-- files: src/lib/core/server/entries/operations/ -->
-- [x] `[fix]` `[P1]` resolveUrlFields: normalize flat string url/text, use raw DB calls <!-- files: src/lib/core/server/entries/ -->
-- [x] `[chore]` `[P1]` Migrate #await to reactive query pattern across admin UI
-
-## 0.5.8 — Media GC
-
-- [x] `[feature]` `[P1]` Image style upsert: replace duplicates instead of creating new files
-- [x] `[feature]` `[P1]` Auto-cleanup old style files from disk on regeneration
-- [x] `[feature]` `[P1]` Admin maintenance page: purge styles, reconcile orphaned disk files
-- [x] `[fix]` `[P1]` Deduplicate existing image style records (keep newest per unique key)
-
-## 0.6.0 — Entity module & DX
-
-- [x] `[feature]` `[P0]` Entity module — programmatic CRUD API for entries (`getEntity`) <!-- files: src/lib/entity/ -->
-- [x] `[feature]` `[P1]` CLI `install-peers` command <!-- files: src/lib/cli/ -->
-- [x] `[feature]` `[P1]` Collection data filters — filter by select/radio fields in toolbar <!-- files: src/lib/admin/client/collection/ -->
-- [x] `[feature]` `[P1]` Layout dot-notation — distribute object fields across layout nodes <!-- files: src/lib/admin/components/fields/ -->
-- [x] `[fix]` `[P1]` AI Claude: lazy client init, no crash without API key <!-- files: src/lib/ai-claude/ -->
-- [x] `[fix]` `[P1]` Codegen: quote hyphenated slugs, PascalCase form schemas, improved query types <!-- files: src/lib/core/server/generator/ -->
-- [x] `[fix]` `[P1]` TipTap: inline block content field lang fix + placeholder UX
-- [x] `[fix]` `[P1]` Zod schema: skip lang wrapper for non-localized content field
-- [x] `[breaking]` `[P0]` Runtime deps → peerDependencies (run `pnpm includio install-peers`)
-
-## 0.6.1 — Admin experience
-
-- [ ] `[feature]` `[P1]` Admin overlay — built-in admin bar on site (quick edit, preview, audit)
-- [ ] `[feature]` `[P1]` Media gallery virtualization/pagination <!-- files: src/lib/admin/components/media/files-list.svelte -->
-- [ ] `[feature]` `[P2]` Image styles UI — preview generated variants in editor
-
-## 0.7.0 — Auth core refactor & design fixes
-
-- [x] `[breaking]` `[P0]` Auth moved into CMS core — lazy betterAuth init from config, AuthAdapter → AuthConfig <!-- files: src/lib/core/cms.ts, src/lib/types/cms.ts, src/lib/sveltekit/server/handle.ts -->
-- [x] `[fix]` `[P1]` Media checkered bg & overlay gradient aligned with design system palette <!-- files: src/lib/admin/styles/admin.css -->
-- [x] `[fix]` `[P1]` Form inputs (input, textarea, select, input-group) use consistent bg-card background
-- [x] `[fix]` `[P2]` Blocks field accordion: rounded borders, card background
-- [x] `[fix]` `[P2]` Media file miniature: reset img/svg margins
-
-## 0.7.1 — Custom fields & admin DX
-
-- [x] `[feature]` `[P0]` Custom fields plugin system — type, zod/TS codegen, field renderer, populate resolver
-- [x] `[feature]` `[P1]` pathTemplate — configurable URL paths for collections/singles
-- [x] `[feature]` `[P1]` Admin public exports: admin/helpers & admin/ui for plugin authors
-- [x] `[feature]` `[P2]` resolveMediaWithStyles utility & core svelte export
-- [x] `[fix]` `[P1]` Schema serialization type cast (stricter TS compatibility)
-
-## 0.7.2 — CLI create-user
-
-- [x] `[feature]` `[P1]` CLI `create-user` command — interactive user creation with role assignment <!-- files: src/lib/cli/create-user.ts, src/lib/cli/index.ts -->
-
-## 0.7.3 — Typography
-
-- [x] `[feature]` `[P1]` Read-time orphan fix — replace space after single-letter Polish conjunctions with `\u00A0` <!-- files: src/lib/core/server/fields/resolveTypographyOrphans.ts, src/lib/core/server/fields/utils/fixOrphans.ts -->
-
-## 0.8.0 — Flat entry format
-
-- [x] `[breaking]` `[P0]` Flat entry format: objects use `_slug` + spread fields instead of `slug` + `data` wrapper
-- [x] `[breaking]` `[P0]` Blocks use `_slug` instead of `slug` with flat fields
-- [x] `[breaking]` `[P0]` `FlatEntry` type removed — use `Entry` instead
-
-## 0.9.0 — Per-language entry versions
-
-- [x] `[breaking]` `[P0]` Per-language entry versions: each language gets its own `entry_version` with flat data
-- [x] `[feature]` `[P0]` Per-language publication: publish/unpublish each language independently
-- [x] `[breaking]` `[P0]` Simplified data format: no more nested `{ pl: "X", en: "Y" }` — values are flat strings
-
-## 0.10.0 — Field type consolidation
-
-- [x] `[breaking]` `[P1]` Remove `image` field type — use `media` with `accept: "image/*"`
-- [x] `[breaking]` `[P1]` Remove `richtext` field type — use `content` (structured JSON)
-- [x] `[chore]` `[P1]` Remove `ImageField`, `RichtextField` interfaces + components
-
-## 0.11.0 — Codegen & REST consolidation
-
-- [x] `[feature]` `[P1]` Codegen: flat types, inline block types, `countEntries`, simplified API
-- [x] `[feature]` `[P1]` REST API: catch-all route, upload endpoint, media endpoint, schema templates
-- [x] `[chore]` `[P1]` Admin scaffold updated for new REST route structure
-
-## 0.12.0 — File field, dataOrderBy, _url
-
-- [x] `[feature]` `[P1]` File field type with multipart upload, validation, rate limiting
-- [x] `[feature]` `[P1]` `dataOrderBy` — sort entries by JSON data fields
-- [x] `[feature]` `[P1]` Auto-populate `_url` field on entries from slug resolver
-
-## 0.13.0 — Private file uploads
-
-- [x] `[feature]` `[P1]` Private file uploads — form submissions can upload files to non-public directory
-
-## 0.13.1 — Admin i18n, codegen cleanup, docs
-
-- [x] `[feature]` `[P1]` Admin UI i18n — TipTap, blocks, array, media components support pl/en <!-- files: src/lib/admin/components/tiptap/lang.ts -->
-- [x] `[feature]` `[P2]` Inline block accordion labels — show field value in collapsed header <!-- files: src/lib/admin/components/tiptap/InlineBlockNodeView.svelte -->
-- [x] `[feature]` `[P2]` Blocks field UrlFieldData label support <!-- files: src/lib/admin/components/fields/blocks-field.svelte -->
-- [x] `[feature]` `[P2]` Email configuration remote endpoint <!-- files: src/lib/admin/remote/email.remote.ts -->
-- [x] `[fix]` `[P1]` Codegen: remove unused Flat*FieldData types, use ImageFieldData/VideoFieldData <!-- files: src/lib/core/server/generator/fields.ts, src/lib/core/server/generator/generator.ts -->
-- [x] `[fix]` `[P1]` Layout renderer: hide card header when label empty <!-- files: src/lib/admin/components/layout/layout-renderer.svelte -->
-- [x] `[fix]` `[P1]` Collection entries: improved relation label fetching (UUID validation, multi-version) <!-- files: src/lib/admin/client/collection/collection-entries.svelte -->
-- [x] `[fix]` `[P1]` Users page: client-side email config, remove server load <!-- files: src/lib/admin/client/users/users-page.svelte -->
-- [x] `[fix]` `[P2]` Entry remote: stricter UUID validation for ids <!-- files: src/lib/admin/remote/entry.remote.ts -->
-- [x] `[fix]` `[P2]` Layout type: remove unused label property <!-- files: src/lib/types/layout.ts -->
-- [x] `[chore]` `[P1]` Documentation rewrite — new pages for blocks, content, media-field, layout; expanded API, auth, entries, forms, plugins docs
-
-## 0.13.2 — Upload limits, stable reordering, image style optimization
-
-- [x] `[feature]` `[P1]` Configurable upload size limit — `BODY_SIZE_LIMIT` env var, pre-validation in UI <!-- files: src/lib/core/server/media/uploadLimit.ts, src/lib/admin/api/upload-limit.ts, src/lib/admin/components/media/file-upload.svelte -->
-- [x] `[feature]` `[P1]` Stable slot reordering — preserve filtered-out entry positions during DnD <!-- files: src/lib/admin/remote/reorder.ts, src/lib/admin/remote/entry.remote.ts -->
-- [x] `[feature]` `[P1]` Collection relation field filtering — filter entries by relation values <!-- files: src/lib/admin/client/collection/collection-entries.svelte -->
-- [x] `[feature]` `[P2]` Expose `_sortOrder` on entries + codegen for orderable collections <!-- files: src/lib/core/server/entries/operations/get.ts, src/lib/core/server/generator/generator.ts, src/lib/types/entries.ts -->
-- [x] `[feature]` `[P2]` `getImageStyleIfExists` — non-blocking image style lookup <!-- files: src/lib/core/server/media/styles/operations/getImageStyle.ts -->
-- [x] `[fix]` `[P1]` Concurrent image style generation with buffer reuse (download once, parallel limit 3) <!-- files: src/lib/core/server/media/styles/operations/generateDefaultStyles.ts, src/lib/core/server/media/styles/sharp/generateImageStyle.ts -->
-- [x] `[fix]` `[P1]` Image style resolution gracefully skips missing styles <!-- files: src/lib/core/server/fields/utils/imageStyles.ts -->
-
-## 0.13.3 — Security hardening
-
-- [x] `[fix]` `[P0]` Timing-safe API key comparison (prevents timing attacks) <!-- files: src/lib/admin/api/rest/middleware/apiKey.ts -->
-- [x] `[fix]` `[P0]` Remove demo reset endpoint with hardcoded fallback secret <!-- files: src/routes/api/demo/reset/ -->
-- [x] `[fix]` `[P1]` Form rate limit: all requests + getClientAddress() instead of x-forwarded-for <!-- files: src/routes/api/forms/[slug]/submit/+server.ts -->
-- [x] `[feature]` `[P1]` MIME blocklist on upload/replace endpoints <!-- files: src/lib/core/server/media/mimeBlocklist.ts -->
-- [x] `[feature]` `[P1]` Security headers: X-Content-Type-Options, X-Frame-Options, Referrer-Policy <!-- files: src/lib/sveltekit/server/handle.ts -->
-- [x] `[fix]` `[P1]` CMS constructor validates non-empty languages array <!-- files: src/lib/core/cms.ts -->
-- [x] `[fix]` `[P2]` Unhandled promise rejection handlers in admin components
-
-## 0.13.4 — Video poster regeneration
-
-- [x] `[feature]` `[P1]` Batch video poster regeneration — admin maintenance page with SSE progress <!-- files: src/lib/admin/api/regenerate-posters.ts, src/lib/core/server/media/operations/batchRegenerateVideoPosters.ts, src/lib/admin/client/maintenance/maintenance-page.svelte -->
-- [x] `[feature]` `[P1]` Video poster status reporting in media GC endpoint <!-- files: src/lib/admin/api/media-gc.ts -->
-- [x] `[chore]` `[P1]` Extracted video processing to reusable module <!-- files: src/lib/files-local/video.ts, src/lib/files-local/index.ts -->
-- [x] `[fix]` `[P1]` Filename sanitization normalizes Unicode to NFC <!-- files: src/lib/files-local/sanitizeFilename.ts -->
-
-## 0.14.0 — Video transcoding
-
-- [x] `[feature]` `[P1]` Video styles system — auto-transcode to mp4 h264 + webm vp9 <!-- files: src/lib/db-postgres/schema/videoStyle.ts, src/lib/files-local/transcode.ts -->
-- [x] `[feature]` `[P1]` Background transcoding pipeline on upload with skip logic <!-- files: src/lib/core/server/media/styles/operations/generateDefaultVideoStyles.ts -->
-- [x] `[feature]` `[P1]` Admin maintenance: video transcoding card (batch, purge, SSE progress) <!-- files: src/lib/admin/client/maintenance/maintenance-page.svelte -->
-- [x] `[feature]` `[P2]` Frontend multi-source video delivery (webm, mp4, original) <!-- files: src/lib/sveltekit/components/video.svelte -->
-- [x] `[feature]` `[P2]` Configurable video transcoding in MediaConfig <!-- files: src/lib/types/cms.ts -->
-- [x] `[feature]` `[P2]` System info endpoint — CMS version, Node, PostgreSQL, ffmpeg, sharp, OS <!-- files: src/lib/admin/api/system-info.ts, src/lib/core/server/media/operations/getSystemInfo.ts -->
-- [x] `[feature]` `[P2]` Disk usage endpoint — breakdown per category (originals, image styles, video styles, posters) <!-- files: src/lib/admin/api/system-info.ts, src/lib/core/server/media/operations/getDiskUsage.ts -->
-
-## 0.14.1 — CMS context, Svelte 5 compat, docs
-
-- [x] `[feature]` `[P1]` CMS context provider — Safari mp4 preference for video delivery <!-- files: src/lib/sveltekit/components/cms-provider.svelte, src/lib/sveltekit/components/video-context.ts, src/lib/types/cms-context.ts -->
-- [x] `[fix]` `[P1]` Svelte 5 compatibility — a11y annotations, warning suppression across admin components
-- [x] `[chore]` `[P1]` Documentation overhaul — new pages, README rewrite, DOCS.md compilation script <!-- files: scripts/compile-docs.ts, DOCS.md -->
-- [x] `[chore]` `[P2]` Remove obsolete docs/ Obsidian config & stale docs
-
-## 0.14.2 — Image styles: aspectRatio, skip defaults, lazy generation
-
-- [x] `[feature]` `[P1]` aspectRatio option for image styles — crop to ratio without fixed dimensions <!-- files: src/lib/types/fields.ts, src/lib/core/server/media/styles/sharp/generateImageStyle.ts, src/lib/db-postgres/schema/imageStyle.ts -->
-- [x] `[feature]` `[P1]` Skip default styles when field defines custom styles (prevents `<source>` conflicts in `<picture>`) <!-- files: src/lib/core/server/fields/utils/imageStyles.ts -->
-- [x] `[feature]` `[P2]` Lazy generation of custom field styles on first read <!-- files: src/lib/core/server/fields/utils/imageStyles.ts -->
-
-## 0.14.3 — Background maintenance
-
-- [x] `[feature]` `[P1]` Background maintenance scheduler — auto styles, posters, transcodes, orphan cleanup on configurable interval <!-- files: src/lib/core/server/media/operations/backgroundMaintenance.ts, src/lib/core/cms.ts -->
-- [x] `[feature]` `[P1]` Maintenance status API endpoint <!-- files: src/lib/admin/api/maintenance-status.ts, src/lib/admin/api/handler.ts -->
-- [x] `[feature]` `[P2]` Configurable maintenance interval via `media.maintenance` config <!-- files: src/lib/types/cms.ts -->
-- [x] `[feature]` `[P1]` Maintenance page UI redesign — status banner, sections, SSE handler dedup <!-- files: src/lib/admin/client/maintenance/maintenance-page.svelte -->
-
-## 0.14.5 — Schema cleanup
-
-- [x] `[chore]` `[P2]` Move image & video style unique indexes into Drizzle ORM schema (single source of truth) <!-- files: src/lib/db-postgres/schema/imageStyle.ts, src/lib/db-postgres/schema/videoStyle.ts -->
-
-## 0.14.6 — Admin page titles
-
-- [x] `[fix]` `[P2]` Admin `<title>` from breadcrumbs + pre-login titles + AriaCMS brand <!-- files: src/lib/admin/utils/pageTitle.ts, src/lib/admin/client/admin/admin-after-login-layout-content.svelte -->
-- [x] `[fix]` `[P1]` Video poster always from first frame (no jump on load) <!-- files: src/lib/files-local/video.ts -->
-- [x] `[feature]` `[P2]` Manual poster regeneration in media library file details <!-- files: src/lib/core/server/media/operations/regenerateVideoPoster.ts, src/lib/admin/components/media/file/file-details.svelte -->
-- [x] `[feature]` `[P2]` Config flag `sidebarHelp` to hide admin sidebar Help link (default true) <!-- files: src/lib/types/cms.ts, src/lib/core/cms.ts, src/routes/admin/(afterLogin)/+layout.server.ts, src/lib/admin/components/layout/nav-footer.svelte -->
-
-## 0.15.0 — Shop MVP (headless e-commerce)
-
-- [x] `[feature]` `[P0]` Scaffold: `defineShop`, types, CMSConfig slot, package export `./shop` <!-- files: src/lib/shop/index.ts, src/lib/shop/types.ts -->
-- [x] `[feature]` `[P0]` Drizzle tables: products (entry-backed), variants, orders, order items, status history, payments, shipping methods, stock reservations <!-- files: src/lib/db-postgres/schema/shop/ -->
-- [x] `[feature]` `[P0]` Runtime `schema.ts` generator for drizzle-kit (core + auth + optional shop) <!-- files: src/lib/core/server/generator/generator.ts, src/lib/db-postgres/schema-core.ts, src/lib/db-postgres/schema-shop.ts -->
-- [x] `[feature]` `[P0]` Rate-limit middleware (checkout/webhook) <!-- files: src/lib/shop/rate-limit.ts -->
-- [x] `[feature]` `[P0]` Built-in `shop` field type — makes entries purchasable, auto-hydrated via populateEntryData <!-- files: src/lib/admin/components/fields/shop-field.svelte, src/lib/shop/server/populate.ts -->
-- [x] `[feature]` `[P0]` Net/gross price toggle + live VAT preview in shop field and shipping form
-- [x] `[feature]` `[P0]` Auto default variant on upsert — cart/order always reference variantId
-- [x] `[feature]` `[P0]` Shop admin: products list (JOIN entries × shop_products), shipping methods CRUD with drag-n-drop reorder + free-above threshold
-- [x] `[feature]` `[P0]` Cart (signed cookie) service + `/api/shop/cart` REST + headless SDK `createShopClient()` <!-- files: src/lib/shop/cart/, src/lib/shop/client/ -->
-- [x] `[feature]` `[P0]` Orders + checkout + `manualAdapter` + status emails (inline HTML, PL/EN) <!-- files: src/lib/shop/server/orders.ts, src/lib/shop/http/checkout-handler.ts -->
-- [x] `[feature]` `[P0]` Stock reservation with 30-min TTL — released on cancel/reject, consumed on paid
-- [x] `[feature]` `[P0]` Admin orders view — list (status + email filter), detail (items, history, customer/address/consents, change status, resend email)
-- [x] `[feature]` `[P0]` Random Crockford base32 order numbers (`XXXXX-XXXXX`), unguessable
-- [x] `[feature]` `[P0]` CLI scaffold provisions all shop routes (admin + public API) in consumer app
-- [x] `[feature]` `[P1]` PayU payment adapter + webhook — shipped in 0.15.1 (access-token-gated order view, idempotent webhooks, MD5 signature, shipping↔payment compat, poll fallback)
-- [ ] `[feature]` `[P1]` Stripe payment adapter + webhook — deferred to 0.15.4
-- [x] `[feature]` `[P2]` InPost carrier adapter — shipped in 0.15.3 (Geowidget v5 picker + ShipX shipments + auto-confirm + webhook status updates)
-
-## 0.15.2 — Price precision fix
-
-- [x] `[fix]` `[P1]` Price drift on reload — storage jako `numeric(20,6)` (PLN z 6dp), brutto round-tripuje bez utraty ±1gr. Snapshot zamówienia dalej w groszach (KSeF). <!-- files: src/lib/db-postgres/schema/shop/product.ts, productVariant.ts, shippingMethod.ts, src/lib/shop/pricing.ts, src/lib/shop/server/cart-hydrate.ts, shipping.ts, shop-data.ts, src/lib/admin/components/fields/shop-field.svelte, src/lib/admin/client/shop/shipping-method-form.svelte -->
-- [x] `[feature]` `[P2]` Variant price toggle netto/brutto (spójne z toggle\'em ceny bazowej)
-- [x] `[feature]` `[P2]` `nodemailerAdapter` — typowanie `transportOptions` jako `SMTPTransport.Options` (OAuth2, pool, itd.)
-
-## 0.15.3 — InPost carrier
-
-- [x] `[feature]` `[P2]` `inpostAdapter()` — Geowidget v5 (`<InpostPicker>` Svelte + raw config endpoint), ShipX shipment create + auto-buy + label PDF + cancel, webhook → status + tracking, per-shipping-method service config, customer tracking display in `<OrderStatus>` + email templates
-- [x] `[chore]` `[P2]` Verbose logging on adapter auto-confirm flow (offer prep wait, buy POST, polling) for sandbox debugging
-
-## 0.15.4 — Forms submission scaffold + best-effort notification emails
-
-- [x] `[feature]` `[P1]` CLI scaffold emits `src/routes/api/forms/[slug]/submit/+server.ts` — public form submit endpoint auto-generated, no manual setup per project <!-- files: src/lib/cli/scaffold/admin.ts, src/lib/cli/scaffold/admin.spec.ts -->
-- [x] `[fix]` `[P0]` `createFormSubmission` — split try/catch so SMTP failure no longer returns `false` (endpoint responded 500 even though submission was persisted); notification email is best-effort, logged via `console.error` <!-- files: src/lib/core/server/forms/submissions/operations/create.ts -->
-- [ ] `[feature]` `[P1]` Built-in `/api/health` + `/api/health/ready` with per-adapter checks (db/files/email/ai) + ręczny SMTP diagnostics panel in maintenance page <!-- files: ideas/health-check-module.md -->
-
-## 0.16.0 — Hard reset
-
-> Start drogi do v1.0.0. Decyzje: **[V1-DECISIONS.md](./V1-DECISIONS.md)** | Workflow: **[V1-WORKFLOW.md](./V1-WORKFLOW.md)**
-
-- [x] `[breaking]` `[P0]` Wycięty `src/lib/inline-edit-proto/` (kod na lokalnym branchu `archive/inline-edit-proto`) — inline edit od zera w v1.x
-- [x] `[breaking]` `[P0]` Wycięty `src/lib/demo/seed.ts` + demo routes (`/demo/*`, `/admin/demo/*`) — demo content od zera w v1.x
-- [x] `[breaking]` `[P0]` Skasowany `ROADMAP-EDITOR.md` (treść na archive branch)
-- [x] `[chore]` `[P2]` `ideas/*.md` przeniesione do `ideas/post-v1/` (lokalnie, w `.gitignore`); `select-field-defaultvalue-bug` promowany do v1.0 fix
-- [x] `[chore]` `[P2]` `V1-DECISIONS.md` jako referencja decyzji v1 dla każdej kolejnej sesji
+> **Versioning:** since 0.16.0 droga do v1.0.0. Pre-v1.0 history → **[ROADMAP-ARCHIVE.md](./ROADMAP-ARCHIVE.md)**.
 
 ## v1.0.0 — Stabilizacja (in progress)
 
-> 13 faz w ~16 sesjach, droga 0.16 → 1.0.0. Lean scope: stabilizacja, security, testy, docs, audit + polish shopa. Bez nowych feature'ów.
+> 13 faz w ~16 sesjach, droga 0.16 → 1.0.0. Lean scope: stabilizacja, security, testy, docs, audit + polish shopa. Bez nowych feature'ów. Decyzje: **[V1-DECISIONS.md](./V1-DECISIONS.md)** | Workflow: **[V1-WORKFLOW.md](./V1-WORKFLOW.md)**.
 
-- [x] `[breaking]` `[P0]` API surface lock — exports trim 26→15, JSDoc tagi (@public/@internal/@experimental), `API.md` autogenerated (0.20.0) <!-- files: package.json, scripts/generate-api-md.ts -->
+- [x] `[breaking]` `[P0]` API surface lock — exports trim 26→16, JSDoc tagi (@public/@internal/@experimental), `API.md` autogenerated (0.20.0) <!-- files: package.json, scripts/generate-api-md.ts -->
 - [x] `[chore]` `[P1]` Faza 6 — Test foundation: docker postgres + integration project + 43 cases (30 REST + 6 shop checkout + 7 webhook signature/idempotency dla PayU/InPost), coverage report <!-- files: tests/integration/rest/, tests/helpers/{rest,shop}.ts, tests/integration/fixtures/shopConfig.ts, tests/setup.ts -->
 - [x] `[chore]` `[P1]` Faza 7 — E2E foundation: Playwright config (storageState reuse, setup project), `db_test_e2e` na 5435, `e2e/setup/global-setup.ts` (drizzle push), `e2e/admin/auth.setup.ts` (sign-up + admin role + login), 4 specy zielone w ~23s: login, collection-crud (blog-post create→edit→archive→permanent-delete), media-upload, user-mgmt (create→delete); data-testid na critical buttons admin <!-- files: playwright.config.ts, e2e/admin/*, src/lib/admin/client/{collection,entry,users}/, src/lib/admin/components/media/file-upload.svelte -->
 - [x] `[chore]` `[P1]` Faza 8 — CI na PR: `.github/workflows/ci.yml` z jobs lint/typecheck/unit/integration (postgres :5434)/e2e (postgres :5435 + playwright cache)/build, pnpm cache, trace artifacts on fail, README CI badge <!-- files: .github/workflows/ci.yml, README.md -->
 - [x] `[breaking]` `[P0]` Faza 9 — DX & config validation (0.22.0): `defineConfig` Zod strict z field path + hint, `CmsError` + `ConfigValidationError` z code/context, resolver throw sites zmigrowane, CLI `--help` per subcommand + `--version`, `.env.example` rozszerzony o `INCLUDIO_*`, README rebuild (TOC + system req + 5-min quickstart), JSDoc body (opis + @param + @returns + @example) na każdym `@public` <!-- files: src/lib/core/errors.ts, src/lib/types/cms.schema.ts, src/lib/sveltekit/config.ts, src/lib/cli/index.ts, README.md, .env.example, src/lib/updates/0.22.0/ -->
+- [x] `[chore]` `[P1]` Faza 10 — Documentation Pass (0.23.0): DOCS.md uzupełnione (number/boolean/date edge cases, REST cURL + error codes, Entries error handling + transactions, Admin UI a11y, Adapter Contracts), nowe sekcje (Stability Promise, Security Model), Migration Guide v0.x → v1.0 master cheatsheet (0.16-0.22), ROADMAP cleanup (pre-v1.0 → ROADMAP-ARCHIVE.md) <!-- files: src/routes/docs/{stability-promise,security}/+page.svx, src/routes/docs/migration/+page.svx, src/routes/docs/_config/nav.ts, scripts/compile-docs.ts, ROADMAP-ARCHIVE.md, src/lib/updates/0.23.0/ -->
+- [x] `[chore]` `[P1]` Faza 11 — Performance Pass (0.24.0): N+1 elimination (`getImageStyle` batch IN query, `getRawEntries` batch entry versions), Sharp srcset `Promise.allSettled` (one timeout doesn't kill batch), background maintenance in-process lock verified + tested, bench infra (`pnpm bench` + representative benchmarks), lazy adapter imports verified <!-- files: src/lib/core/server/media/styles/operations/, src/lib/core/server/fields/resolveImageFields.ts, src/lib/core/server/entries/operations/get.ts, src/lib/db-postgres/index.ts, src/lib/core/server/media/operations/backgroundMaintenance.spec.ts, src/lib/updates/0.24.0/ -->
 - [ ] `[fix]` `[P1]` Select field — `defaultValue` propagacja do zod schema (full repro: `ideas/post-v1/select-field-defaultvalue-bug.md`); fix planowany w Fazie 12 (RC)
 
 ## v1.x — Post-v1.0 deferred

package/dist/core/server/entries/operations/get.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/server/entries/operations/get.bench.js

@@ -0,0 +1,68 @@
+import { bench, describe, vi, beforeAll } from 'vitest';
+const QUERY_LATENCY_MS = 1;
+const ENTRY_COUNT = 100;
+function buildDbEntry(i) {
+    return {
+        id: `entry-${i}`,
+        slug: 'blog-post',
+        type: 'collection',
+        sortOrder: i,
+        archivedAt: null,
+        createdAt: new Date(),
+        updatedAt: new Date()
+    };
+}
+function buildVersion(entryId, n) {
+    return {
+        id: `${entryId}-v${n}`,
+        entryId,
+        versionNumber: n,
+        lang: 'en',
+        data: { title: `Entry ${entryId} v${n}` },
+        publishedAt: n === 2 ? new Date(Date.now() - 1000) : null,
+        createdAt: new Date(),
+        updatedAt: new Date()
+    };
+}
+const dbEntries = Array.from({ length: ENTRY_COUNT }, (_, i) => buildDbEntry(i));
+const allVersions = dbEntries.flatMap((e) => [buildVersion(e.id, 1), buildVersion(e.id, 2)]);
+const adapter = {
+    getEntries: vi.fn(async (_options) => {
+        await new Promise((r) => setTimeout(r, QUERY_LATENCY_MS));
+        return dbEntries;
+    }),
+    getEntryVersions: vi.fn(async (options) => {
+        await new Promise((r) => setTimeout(r, QUERY_LATENCY_MS));
+        const ids = new Set(options.entryIds ?? []);
+        return allVersions.filter((v) => ids.has(v.entryId));
+    })
+};
+vi.mock('$lib/core/cms.js', () => ({
+    getCMS: () => ({
+        databaseAdapter: adapter,
+        getBySlug: () => ({ slug: 'blog-post', type: 'collection', orderable: false })
+    })
+}));
+let _getRawEntries;
+beforeAll(async () => {
+    const mod = await import('./get.js');
+    _getRawEntries = mod._getRawEntries;
+});
+describe('_getRawEntries — batch path (current implementation)', () => {
+    bench(`100 entries × 2 versions each — 1 batch getEntryVersions call`, async () => {
+        await _getRawEntries({ slug: 'blog-post' });
+    });
+});
+describe('synthetic N+1 vs batch comparison', () => {
+    bench(`baseline: ${ENTRY_COUNT} sequential per-entry getEntryVersions calls`, async () => {
+        // Simulates the pre-0.24.0 N+1 pattern: one query per entry.
+        await new Promise((r) => setTimeout(r, QUERY_LATENCY_MS)); // getEntries
+        for (let i = 0; i < ENTRY_COUNT; i++) {
+            await new Promise((r) => setTimeout(r, QUERY_LATENCY_MS));
+        }
+    });
+    bench('batched: 1 getEntries + 1 getEntryVersions', async () => {
+        await new Promise((r) => setTimeout(r, QUERY_LATENCY_MS));
+        await new Promise((r) => setTimeout(r, QUERY_LATENCY_MS));
+    });
+});

package/dist/core/server/entries/operations/get.js

@@ -55,16 +55,26 @@ function buildPerLangVersionMaps(versions) {
 }
 export const _getRawEntries = async (options) => {
     const dbEntries = await _getDbEntries(options);
-    const entries = await Promise.all(dbEntries.map(async (entry) => {
+    if (dbEntries.length === 0)
+        return [];
+    const cms = getCMS();
+    const allVersions = await cms.databaseAdapter.getEntryVersions({
+        entryIds: dbEntries.map((e) => e.id)
+    });
+    const versionsByEntry = new Map();
+    for (const v of allVersions) {
+        const arr = versionsByEntry.get(v.entryId) || [];
+        arr.push(v);
+        versionsByEntry.set(v.entryId, arr);
+    }
+    const entries = dbEntries.map((entry) => {
         try {
-            const versions = await getCMS().databaseAdapter.getEntryVersions({
-                entryIds: [entry.id]
-            });
+            const versions = versionsByEntry.get(entry.id) ?? [];
             const { publishedVersions, scheduledVersions, draftVersions } = buildPerLangVersionMaps(versions);
             return {
                 ...entry,
-                collection: getCMS().getBySlug(entry.slug),
-                versions: versions.sort((a, b) => b.versionNumber - a.versionNumber),
+                collection: cms.getBySlug(entry.slug),
+                versions: [...versions].sort((a, b) => b.versionNumber - a.versionNumber),
                 publishedVersions,
                 scheduledVersions,
                 draftVersions
@@ -74,7 +84,7 @@ export const _getRawEntries = async (options) => {
             // Orphaned entry - slug removed from config
             return null;
         }
-    }));
+    });
     return entries.filter((e) => e !== null);
 };
 export const _getRawEntry = async (options) => {

package/dist/core/server/fields/utils/imageStyles.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/server/fields/utils/imageStyles.bench.js

@@ -0,0 +1,82 @@
+import { bench, describe, vi, beforeAll } from 'vitest';
+import { imageStyleKey } from '../../../../types/adapters/db.js';
+vi.mock('../../media/utils/generateBlurDataUrl.js', () => ({
+    generateBlurDataUrl: vi.fn().mockResolvedValue('data:image/webp;base64,abc')
+}));
+const QUERY_LATENCY_MS = 1;
+function fakeStyle(req) {
+    return {
+        url: `/uploads/${req.mediaFileId}-${req.style.name}.${req.style.format ?? 'webp'}`,
+        mimeType: `image/${req.style.format ?? 'webp'}`
+    };
+}
+const batchAdapter = {
+    getImageStyle: vi.fn(async (mediaFileId, style) => {
+        await new Promise((r) => setTimeout(r, QUERY_LATENCY_MS));
+        return fakeStyle({ mediaFileId, style });
+    }),
+    getImageStylesBatch: vi.fn(async (requests) => {
+        await new Promise((r) => setTimeout(r, QUERY_LATENCY_MS));
+        const map = new Map();
+        for (const r of requests)
+            map.set(imageStyleKey(r.mediaFileId, r.style), fakeStyle(r));
+        return map;
+    }),
+    updateMediaFile: vi.fn().mockResolvedValue(undefined)
+};
+vi.mock('$lib/core/cms.js', () => ({
+    getCMS: () => ({
+        databaseAdapter: batchAdapter,
+        filesAdapter: { downloadFile: vi.fn().mockResolvedValue(null) }
+    })
+}));
+let getImageStyles;
+beforeAll(async () => {
+    const mod = await import('./imageStyles.js');
+    getImageStyles = mod.getImageStyles;
+});
+const mediaFile = {
+    id: 'media-1',
+    name: 'photo.jpg',
+    url: '/uploads/photo.jpg',
+    type: 'image',
+    size: 1024,
+    width: 3000,
+    height: 2000,
+    alt: null,
+    tags: [],
+    createdAt: new Date(),
+    thumbnailUrl: null,
+    duration: null,
+    posterUrl: null,
+    mimeType: 'image/jpeg',
+    blurDataUrl: 'data:image/webp;base64,existing',
+    focalX: null,
+    focalY: null,
+    transcriptFileId: null,
+    audioDescriptionFileId: null
+};
+const customStyles = [
+    { name: 'card', width: 600, srcset: [320, 640, 1024] },
+    { name: 'hero', width: 1920, srcset: [640, 1024, 1920, 2560] },
+    { name: 'thumb', width: 200 }
+];
+const field = { styles: customStyles };
+describe('getImageStyles — batch path (current implementation)', () => {
+    bench('1 media × 3 styles × 3 formats × srcset (1 batch query)', async () => {
+        await getImageStyles(field, mediaFile);
+    });
+});
+describe('synthetic N+1 vs batch comparison', () => {
+    const styleCount = 3 * 3; // 3 styles × 3 format expansions
+    const srcsetCount = 7; // total srcset variants across the 3 styles
+    const totalLookups = styleCount + styleCount * srcsetCount; // ~72 per media
+    bench(`baseline: ${totalLookups} sequential per-style queries`, async () => {
+        for (let i = 0; i < totalLookups; i++) {
+            await new Promise((r) => setTimeout(r, QUERY_LATENCY_MS));
+        }
+    });
+    bench('batched: 1 query covers all lookups', async () => {
+        await new Promise((r) => setTimeout(r, QUERY_LATENCY_MS));
+    });
+});