includio-cms 0.36.9 → 0.37.1

package/dist/shop/index.js

@@ -1,4 +1,5 @@
-export function defineShop(config) {
+/** Resolves a raw {@link ShopConfig} into a fully-defaulted {@link ResolvedShopConfig}. */
+function resolveShopConfig(config) {
     return {
         ...config,
         features: {
@@ -22,6 +23,47 @@ export function defineShop(config) {
         cartName: config.cartName ?? null
     };
 }
+/** Server-only init for the shop module — applies GIN indexes + smoke-tests email templates. */
+async function shopModuleInit({ drizzle, config, defaultLanguage }) {
+    const shop = config;
+    if (drizzle) {
+        const { applyVariantAttributeIndexes } = await import('./server/init.js');
+        await applyVariantAttributeIndexes(shop, drizzle);
+    }
+    // Smoke-test built-in shop email templates — fast lookup-only sweep. Catches
+    // corrupt installs (missing dist files) at boot instead of at first send.
+    const { REQUIRED_TEMPLATE_NAMES } = await import('./server/email.js');
+    const { validateBuiltinTemplates } = await import('./server/emailTemplateRegistry.js');
+    validateBuiltinTemplates([...REQUIRED_TEMPLATE_NAMES], defaultLanguage);
+}
+/**
+ * Defines the shop module. Returns a {@link CMSModule} for
+ * `defineConfig({ modules: [defineShop({...})] })`. The resolved shop config
+ * is carried on `module.config` and reachable via `getCMS().getModuleConfig('shop')`
+ * (or the back-compat `getCMS().shopConfig`).
+ *
+ * @public
+ */
+export function defineShop(config) {
+    const resolved = resolveShopConfig(config);
+    return {
+        id: 'shop',
+        label: { pl: 'Sklep', en: 'Shop' },
+        icon: 'building-store',
+        context: {
+            contextLabel: { pl: 'Sklep', en: 'Shop' },
+            landingUrl: '/admin/shop',
+            sections: [
+                { key: 'products', title: { pl: 'Produkty', en: 'Products' }, url: '/admin/shop/products', icon: 'package' },
+                { key: 'orders', title: { pl: 'Zamówienia', en: 'Orders' }, url: '/admin/shop/orders', icon: 'shopping-cart' },
+                { key: 'shipping', title: { pl: 'Metody wysyłki', en: 'Shipping methods' }, url: '/admin/shop/shipping-methods', icon: 'truck' },
+                { key: 'coupons', title: { pl: 'Kody rabatowe', en: 'Coupon codes' }, url: '/admin/shop/coupons', icon: 'ticket' }
+            ]
+        },
+        config: resolved,
+        serverHooks: { init: shopModuleInit }
+    };
+}
 export { InvalidVariantAttributesError } from './variant-attributes.js';
 export { isVariantExpired, filterUpcoming, VariantExpiredError } from './expiry.js';
 export { manualAdapter } from './adapters/manual/index.js';

package/dist/shop/rate-limit.d.ts

@@ -1,9 +1 @@
-import type { RateLimitRule } from './types.js';
-export interface RateLimitResult {
-    allowed: boolean;
-    remaining: number;
-    resetAt: number;
-}
-export declare function checkRateLimit(key: string, rule: RateLimitRule): RateLimitResult;
-export declare function resetRateLimit(key?: string): void;
-export declare function clientKey(req: Request, prefix: string): string;
+export { checkRateLimit, resetRateLimit, clientKey, type RateLimitResult } from '../server/security/rate-limit-handler.js';

package/dist/shop/rate-limit.js

@@ -1,28 +1,3 @@
-const buckets = new Map();
-export function checkRateLimit(key, rule) {
-    const now = Date.now();
-    const windowMs = rule.windowSec * 1000;
-    const bucket = buckets.get(key);
-    if (!bucket || bucket.resetAt <= now) {
-        const fresh = { count: 1, resetAt: now + windowMs };
-        buckets.set(key, fresh);
-        return { allowed: true, remaining: rule.limit - 1, resetAt: fresh.resetAt };
-    }
-    if (bucket.count >= rule.limit) {
-        return { allowed: false, remaining: 0, resetAt: bucket.resetAt };
-    }
-    bucket.count += 1;
-    return { allowed: true, remaining: rule.limit - bucket.count, resetAt: bucket.resetAt };
-}
-export function resetRateLimit(key) {
-    if (key)
-        buckets.delete(key);
-    else
-        buckets.clear();
-}
-export function clientKey(req, prefix) {
-    const ip = req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ||
-        req.headers.get('x-real-ip') ||
-        'unknown';
-    return `${prefix}:${ip}`;
-}
+// Lifted to core (`$lib/server/security/rate-limit-handler`) so shop + booking
+// share one generic per-handler limiter without a booking→shop dependency.
+export { checkRateLimit, resetRateLimit, clientKey } from '../server/security/rate-limit-handler.js';

package/dist/shop/types.d.ts

@@ -70,6 +70,25 @@ export interface ConsentConfig {
 export interface PaymentCreateContext {
     customerIp?: string;
     language?: string | null;
+    /**
+     * Fully-resolved absolute return URL. When set, adapters MUST use it verbatim
+     * and skip any shop-order hydration — lets non-shop callers (e.g. booking)
+     * reuse the adapter without a shop module.
+     */
+    continueUrl?: string;
+    /** Caller-supplied buyer identity (for non-shop callers). */
+    buyer?: {
+        firstName?: string;
+        lastName?: string;
+        phone?: string;
+    };
+    /**
+     * Unique external id for THIS payment attempt. Adapters whose provider requires
+     * a unique-per-attempt order id (e.g. PayU's `extOrderId`, unique per POS) use
+     * it instead of `order.number`. Required when one order/booking spawns multiple
+     * provider orders (deposit + balance), otherwise the provider rejects the reuse.
+     */
+    externalId?: string;
 }
 /**
  * Result of a non-invasive integration connectivity check. Returned by an

package/dist/sveltekit/config.d.ts

@@ -19,6 +19,10 @@ type SingleInput = Omit<SingleConfig, 'fields'> & {
  * (extends `CmsError`) listing every issue with a path and a fix hint, e.g.
  *   `languages[0].code: must be a 2-letter ISO code (e.g. 'en')`
  *
+ * Also checks preview views: unique names, at most one `default`, `previewUrl`
+ * and `previews` are mutually exclusive, and every `tab.preview` points at a
+ * declared view.
+ *
  * @param config - The CMSConfig (collections, singles, forms, adapters, languages, ...).
  * @returns The same config, parsed and frozen against typos.
  * @throws {ConfigValidationError} when validation fails — message aggregates all issues.

package/dist/sveltekit/config.js

@@ -1,5 +1,6 @@
 import { cmsConfigSchema } from '../types/cms.schema.js';
 import { formatConfigError } from '../core/errors.js';
+import { validatePreviews } from '../core/config/validatePreviews.js';
 /**
  * Defines the root CMS configuration. Pass to `includioCMS()` in `hooks.server.ts`.
  *
@@ -7,6 +8,10 @@ import { formatConfigError } from '../core/errors.js';
  * (extends `CmsError`) listing every issue with a path and a fix hint, e.g.
  *   `languages[0].code: must be a 2-letter ISO code (e.g. 'en')`
  *
+ * Also checks preview views: unique names, at most one `default`, `previewUrl`
+ * and `previews` are mutually exclusive, and every `tab.preview` points at a
+ * declared view.
+ *
  * @param config - The CMSConfig (collections, singles, forms, adapters, languages, ...).
  * @returns The same config, parsed and frozen against typos.
  * @throws {ConfigValidationError} when validation fails — message aggregates all issues.
@@ -26,6 +31,7 @@ export function defineConfig(config) {
     if (!result.success) {
         throw formatConfigError(result.error);
     }
+    validatePreviews(config);
     return config;
 }
 /**

package/dist/types/cms.d.ts

@@ -9,6 +9,7 @@ import type { AIAdapter } from './adapters/ai.js';
 import type { EmailAdapter } from './adapters/email.js';
 import type { ResolvedShopConfig } from '../shop/types.js';
 import type { ResolvedCmpConfig } from '../cmp/types.js';
+import type { CMSModule } from './modules.js';
 export interface VideoTranscodeConfig {
     /** Enable/disable auto-transcoding on upload (default: true) */
     transcode?: boolean;
@@ -157,7 +158,12 @@ export interface CMSConfig {
     apiKeys?: ApiKeyConfig[];
     typography?: TypographyConfig;
     sidebarHelp?: boolean;
-    shop?: ResolvedShopConfig;
+    /**
+     * Optional modules ("overlays") layered on the CMS core — shop, booking,
+     * etc. Each is a {@link CMSModule} (typically from `defineShop()` /
+     * `defineBooking()`). Renders a context in the admin switcher.
+     */
+    modules?: CMSModule[];
     cmp?: ResolvedCmpConfig;
     admin?: AdminConfig;
 }
@@ -180,4 +186,12 @@ export interface ICMS {
     shopConfig: ResolvedShopConfig | null;
     cmpConfig: ResolvedCmpConfig | null;
     adminConfig: AdminConfig | null;
+    /** Registered modules ("overlays"), keyed by `module.id`. */
+    modules: Map<string, CMSModule>;
+    /** Returns a registered module by id, or `undefined`. */
+    getModule(id: string): CMSModule | undefined;
+    /** Returns a registered module's `config`, narrowed to `T`, or `undefined`. */
+    getModuleConfig<T = unknown>(id: string): T | undefined;
+    /** Whether a module with the given id is registered. */
+    hasModule(id: string): boolean;
 }

package/dist/types/cms.schema.d.ts

@@ -34,6 +34,12 @@ export declare const cmsConfigSchema: z.ZodObject<{
         slug: z.ZodString;
         sidebarIcon: z.ZodOptional<z.ZodString>;
         previewUrl: z.ZodOptional<z.ZodString>;
+        previews: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            label: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+            url: z.ZodString;
+            default: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>>;
         fields: z.ZodArray<z.ZodType<FieldDef, unknown, z.core.$ZodTypeInternals<FieldDef, unknown>>>;
         layout: z.ZodOptional<z.ZodUnknown>;
         slugField: z.ZodOptional<z.ZodString>;
@@ -44,6 +50,12 @@ export declare const cmsConfigSchema: z.ZodObject<{
         slug: z.ZodString;
         sidebarIcon: z.ZodOptional<z.ZodString>;
         previewUrl: z.ZodOptional<z.ZodString>;
+        previews: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            label: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+            url: z.ZodString;
+            default: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>>;
         fields: z.ZodArray<z.ZodType<FieldDef, unknown, z.core.$ZodTypeInternals<FieldDef, unknown>>>;
         layout: z.ZodOptional<z.ZodUnknown>;
         slugField: z.ZodOptional<z.ZodString>;
@@ -145,7 +157,26 @@ export declare const cmsConfigSchema: z.ZodObject<{
         fixOrphans: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>;
     sidebarHelp: z.ZodOptional<z.ZodBoolean>;
-    shop: z.ZodOptional<z.ZodUnknown>;
+    modules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+        icon: z.ZodString;
+        context: z.ZodObject<{
+            contextLabel: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+            landingUrl: z.ZodString;
+            sections: z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                title: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                url: z.ZodString;
+                icon: z.ZodString;
+                countSource: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+            surfacedCollections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            surfacedSingles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$loose>;
+        config: z.ZodOptional<z.ZodUnknown>;
+        serverHooks: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
     cmp: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$loose>;
 export type CmsConfigSchema = z.infer<typeof cmsConfigSchema>;
@@ -228,6 +259,12 @@ export declare const _internal: {
         slug: z.ZodString;
         sidebarIcon: z.ZodOptional<z.ZodString>;
         previewUrl: z.ZodOptional<z.ZodString>;
+        previews: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            label: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+            url: z.ZodString;
+            default: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>>;
         fields: z.ZodArray<z.ZodType<FieldDef, unknown, z.core.$ZodTypeInternals<FieldDef, unknown>>>;
         layout: z.ZodOptional<z.ZodUnknown>;
         slugField: z.ZodOptional<z.ZodString>;
@@ -238,6 +275,12 @@ export declare const _internal: {
         slug: z.ZodString;
         sidebarIcon: z.ZodOptional<z.ZodString>;
         previewUrl: z.ZodOptional<z.ZodString>;
+        previews: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            label: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+            url: z.ZodString;
+            default: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>>;
         fields: z.ZodArray<z.ZodType<FieldDef, unknown, z.core.$ZodTypeInternals<FieldDef, unknown>>>;
         layout: z.ZodOptional<z.ZodUnknown>;
         slugField: z.ZodOptional<z.ZodString>;
@@ -314,6 +357,26 @@ export declare const _internal: {
         label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
         notificationEmailAddresses: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$loose>;
+    moduleSchema: z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+        icon: z.ZodString;
+        context: z.ZodObject<{
+            contextLabel: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+            landingUrl: z.ZodString;
+            sections: z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                title: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                url: z.ZodString;
+                icon: z.ZodString;
+                countSource: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+            surfacedCollections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            surfacedSingles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$loose>;
+        config: z.ZodOptional<z.ZodUnknown>;
+        serverHooks: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
     cmsConfigBaseSchema: z.ZodObject<{
         languages: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
             code: z.ZodString;
@@ -331,6 +394,12 @@ export declare const _internal: {
             slug: z.ZodString;
             sidebarIcon: z.ZodOptional<z.ZodString>;
             previewUrl: z.ZodOptional<z.ZodString>;
+            previews: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                label: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                url: z.ZodString;
+                default: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$loose>>>;
             fields: z.ZodArray<z.ZodType<FieldDef, unknown, z.core.$ZodTypeInternals<FieldDef, unknown>>>;
             layout: z.ZodOptional<z.ZodUnknown>;
             slugField: z.ZodOptional<z.ZodString>;
@@ -341,6 +410,12 @@ export declare const _internal: {
             slug: z.ZodString;
             sidebarIcon: z.ZodOptional<z.ZodString>;
             previewUrl: z.ZodOptional<z.ZodString>;
+            previews: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                label: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                url: z.ZodString;
+                default: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$loose>>>;
             fields: z.ZodArray<z.ZodType<FieldDef, unknown, z.core.$ZodTypeInternals<FieldDef, unknown>>>;
             layout: z.ZodOptional<z.ZodUnknown>;
             slugField: z.ZodOptional<z.ZodString>;
@@ -442,7 +517,26 @@ export declare const _internal: {
             fixOrphans: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$loose>>;
         sidebarHelp: z.ZodOptional<z.ZodBoolean>;
-        shop: z.ZodOptional<z.ZodUnknown>;
+        modules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+            icon: z.ZodString;
+            context: z.ZodObject<{
+                contextLabel: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                landingUrl: z.ZodString;
+                sections: z.ZodArray<z.ZodObject<{
+                    key: z.ZodString;
+                    title: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                    url: z.ZodString;
+                    icon: z.ZodString;
+                    countSource: z.ZodOptional<z.ZodString>;
+                }, z.core.$loose>>;
+                surfacedCollections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                surfacedSingles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$loose>;
+            config: z.ZodOptional<z.ZodUnknown>;
+            serverHooks: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$loose>>>;
         cmp: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$loose>;
     FIELD_TYPES: readonly ["text", "content", "number", "boolean", "date", "datetime", "file", "media", "select", "radio", "checkboxes", "relation", "object", "array", "blocks", "slug", "seo", "shop", "url", "icon", "custom"];

package/dist/types/cms.schema.js

@@ -344,10 +344,19 @@ const formFieldSchema = z.discriminatedUnion('type', [
 /* -------------------------------------------------------------------------- */
 /*                          Collections / Singles / Forms                      */
 /* -------------------------------------------------------------------------- */
+const previewViewSchema = z
+    .object({
+    name: z.string().min(1, { message: 'preview view must have a name' }),
+    label: localizedSchema.optional(),
+    url: z.string().min(1, { message: 'preview view must have a url' }),
+    default: z.boolean().optional()
+})
+    .passthrough();
 const configBaseShape = {
     slug: slugSchema,
     sidebarIcon: z.string().optional(),
     previewUrl: z.string().optional(),
+    previews: z.array(previewViewSchema).optional(),
     fields: z.array(fieldSchema).min(1, {
         message: 'must declare at least one field'
     }),
@@ -436,6 +445,39 @@ const apiKeySchema = z
 })
     .passthrough();
 /* -------------------------------------------------------------------------- */
+/*                                  Modules                                    */
+/* -------------------------------------------------------------------------- */
+const moduleNavSectionSchema = z
+    .object({
+    key: z.string().min(1, { message: 'module nav section.key is required' }),
+    title: localizedSchema,
+    url: z.string().min(1, { message: 'module nav section.url is required' }),
+    icon: z.string().min(1, { message: 'module nav section.icon is required' }),
+    countSource: z.string().optional()
+})
+    .passthrough();
+const moduleContextSchema = z
+    .object({
+    contextLabel: localizedSchema.optional(),
+    landingUrl: z.string().min(1, { message: 'module context.landingUrl is required' }),
+    sections: z.array(moduleNavSectionSchema),
+    surfacedCollections: z.array(z.string()).optional(),
+    surfacedSingles: z.array(z.string()).optional()
+})
+    .passthrough();
+const moduleSchema = z
+    .object({
+    id: slugSchema,
+    label: localizedSchema,
+    icon: z.string().min(1, { message: 'module.icon is required' }),
+    context: moduleContextSchema,
+    // `config` holds adapter functions / resolved module config — opaque.
+    config: z.unknown().optional(),
+    // `serverHooks` holds functions — never validated, never serialized.
+    serverHooks: z.unknown().optional()
+})
+    .passthrough();
+/* -------------------------------------------------------------------------- */
 /*                                 CMSConfig                                   */
 /* -------------------------------------------------------------------------- */
 const cmsConfigBaseSchema = z
@@ -465,7 +507,7 @@ const cmsConfigBaseSchema = z
         .passthrough()
         .optional(),
     sidebarHelp: z.boolean().optional(),
-    shop: z.unknown().optional(),
+    modules: z.array(moduleSchema).optional(),
     cmp: z.unknown().optional()
 })
     .passthrough();
@@ -625,6 +667,46 @@ export const cmsConfigSchema = cmsConfigBaseSchema.superRefine((data, ctx) => {
             }
         }
     });
+    // Module id uniqueness + surfaced collection/single references
+    const moduleIds = new Set();
+    (data.modules ?? []).forEach((m, i) => {
+        const mod = m;
+        const id = mod.id;
+        if (typeof id === 'string') {
+            if (moduleIds.has(id)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['modules', i, 'id'],
+                    message: `duplicate module id '${id}'`
+                });
+            }
+            moduleIds.add(id);
+        }
+        const surfacedCollections = mod.context?.surfacedCollections;
+        if (Array.isArray(surfacedCollections)) {
+            surfacedCollections.forEach((slug, j) => {
+                if (!collectionSlugs.has(slug)) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ['modules', i, 'context', 'surfacedCollections', j],
+                        message: `surfaced collection '${slug}' does not reference a declared collection`
+                    });
+                }
+            });
+        }
+        const surfacedSingles = mod.context?.surfacedSingles;
+        if (Array.isArray(surfacedSingles)) {
+            surfacedSingles.forEach((slug, j) => {
+                if (!singleSlugs.has(slug)) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ['modules', i, 'context', 'surfacedSingles', j],
+                        message: `surfaced single '${slug}' does not reference a declared single`
+                    });
+                }
+            });
+        }
+    });
 });
 /** Exposed for tests only. Not part of the public API. */
 export const _internal = {
@@ -633,6 +715,7 @@ export const _internal = {
     collectionSchema,
     singleSchema,
     formSchema,
+    moduleSchema,
     cmsConfigBaseSchema,
     FIELD_TYPES,
     FORM_FIELD_TYPES,

package/dist/types/config.d.ts

@@ -1,10 +1,43 @@
 import type { Field } from './fields.js';
 import type { IconName } from '../admin/components/icons/icon-map.js';
 import type { Layout } from './layout.js';
+import type { Localized } from './languages.js';
+/**
+ * A named preview target. The same entry is often rendered in more than one way
+ * on the front end — a full page and a teaser card in a listing — and each way
+ * is a view.
+ *
+ * The admin loads `{url}?preview={entryId}&view={name}` in the preview iframe,
+ * so a project may expose one route per view, or a single route that branches
+ * on the `view` query param. Views do not change what is fetched from the
+ * database — the entry always arrives whole.
+ *
+ * @public
+ * @example
+ * ```ts
+ * previews: [
+ *   { name: 'full', label: { pl: 'Pełny wpis' }, url: '/preview/blog-post' },
+ *   { name: 'teaser', label: { pl: 'Zajawka' }, url: '/preview/blog-post/teaser' }
+ * ]
+ * ```
+ */
+export interface PreviewView {
+    /** Stable identifier, referenced by `TabNode.preview`. */
+    name: string;
+    /** Switcher label. Defaults to `name`. */
+    label?: Localized;
+    /** Preview route, e.g. '/preview/blog-post/teaser'. */
+    url: string;
+    /** Start view. Defaults to the first entry of the array. */
+    default?: boolean;
+}
 export interface ConfigBase {
     sidebarIcon?: IconName;
     slug: string;
+    /** Shorthand for a single preview view. Mutually exclusive with `previews`. */
     previewUrl?: string;
+    /** Named preview views. Mutually exclusive with `previewUrl`. */
+    previews?: PreviewView[];
     fields: Field[];
     layout?: Layout;
     slugField?: string;

package/dist/types/layout.d.ts

@@ -81,6 +81,12 @@ export interface TabsNode extends LayoutNodeBase {
 export interface TabNode extends LayoutNodeBase {
     type: 'tab';
     label: Localized;
+    /**
+     * Name of a view from `previews[]`. Entering this tab switches the preview to
+     * that view, unless the user manually picked another view while on this tab.
+     * A tab without `preview` leaves the current view alone.
+     */
+    preview?: string;
     fields?: string[];
     children?: LayoutNode[];
 }

package/dist/types/modules.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Module system — shop, booking, and future "overlays" on the CMS core.
+ *
+ * A module is registered via `defineConfig({ modules: [...] })`. It is split
+ * into a **serializable descriptor** (id/label/icon/context — safe to send to
+ * the admin client via a remote query) and **server-only `serverHooks`**
+ * (init logic that must never cross the wire). The module's dashboard
+ * component lives in a separate client-side registry keyed by `id`, never in
+ * the config — Svelte components are not serializable and the config is also
+ * validated server-side with Zod.
+ *
+ * @see {@link CMSModule}
+ */
+/** A label that is either a plain string or a `{ lang: text }` map. */
+export type LocalizedText = string | Record<string, string>;
+/**
+ * One sidebar entry contributed by a module's context. Icons are referenced
+ * by **name** (resolved client-side via the admin icon-map), never as a
+ * component, so the descriptor stays serializable and userland never needs an
+ * icon library as a dependency.
+ *
+ * @public
+ */
+export interface ModuleNavSection {
+    /** Stable key for keyed rendering and active-state checks. */
+    key: string;
+    /** Display title. */
+    title: LocalizedText;
+    /** Target route, e.g. `/admin/shop/orders`. */
+    url: string;
+    /** Icon name from the admin icon-map, e.g. `shopping-cart`. */
+    icon: string;
+    /**
+     * Optional remote-query name returning a `number`, rendered as a badge and
+     * resolved reactively on the client (same pattern as collection entry
+     * counts). Omit for sections without a count.
+     */
+    countSource?: string;
+}
+/**
+ * The curated workspace a module contributes: a landing (dashboard) target,
+ * its own nav sections, and optional **surfaced** core collections/singles
+ * pulled into the module's context (e.g. shop surfaces the `products`
+ * collection as "Products").
+ *
+ * @public
+ */
+export interface ModuleContext {
+    /** Switcher label for this context. Defaults to the module's `label`. */
+    contextLabel?: LocalizedText;
+    /** Where selecting this context navigates, e.g. `/admin/shop`. */
+    landingUrl: string;
+    /** Static nav sections owned by the module. */
+    sections: ModuleNavSection[];
+    /** Slugs of core collections surfaced inside this context. */
+    surfacedCollections?: string[];
+    /** Slugs of core singles surfaced inside this context. */
+    surfacedSingles?: string[];
+}
+/** Context passed to a module's `serverHooks.init`. */
+export interface ModuleInitContext {
+    /** Raw drizzle handle (`databaseAdapter._drizzle`), or `undefined`. */
+    drizzle: unknown;
+    /** The module's own resolved config (same reference as `CMSModule.config`). */
+    config: unknown;
+    /** The CMS default language code (first configured language). */
+    defaultLanguage: string;
+}
+/**
+ * Server-only module hooks. NEVER serialized or sent to the admin client —
+ * stripped from the descriptor returned by `getModules()`.
+ *
+ * @public
+ */
+export interface ModuleServerHooks {
+    /**
+     * Idempotent boot-time init run by `initCMS` (e.g. create indexes,
+     * smoke-test templates). Non-blocking: errors are logged, not thrown.
+     *
+     * Define this ONLY in a server-only module. A module whose factory (e.g.
+     * `defineBooking`) is re-exported from a client-safe barrel MUST NOT inline a
+     * server import here — bundlers create a chunk for it and break browser builds.
+     * Use {@link initModule} instead.
+     */
+    init?: (ctx: ModuleInitContext) => Promise<void> | void;
+    /**
+     * Bare package specifier of a SERVER-ONLY module exporting `serverInit(ctx)`,
+     * run by `initCMS` at boot. Prefer this over {@link init} when the module's
+     * factory lives in a client-safe barrel: it is a plain string (no import), so
+     * the client bundle stays free of server code. `initCMS` (server-only) resolves
+     * and imports it at runtime from node_modules. Ignored if {@link init} is set.
+     */
+    initModule?: string;
+}
+/**
+ * A CMS module ("overlay"): shop, booking, etc. Register via
+ * `defineConfig({ modules: [defineShop(...), defineBooking(...)] })`.
+ *
+ * @public
+ */
+export interface CMSModule {
+    /** Unique slug, e.g. `shop` | `booking`. */
+    id: string;
+    /** Display label (switcher + sidebar group label). */
+    label: LocalizedText;
+    /** Icon name from the admin icon-map, e.g. `building-store`. */
+    icon: string;
+    /** The curated workspace this module contributes. */
+    context: ModuleContext;
+    /** The module's typed resolved config — opaque to the framework. */
+    config?: unknown;
+    /** Server-only hooks (not part of the serialized descriptor). */
+    serverHooks?: ModuleServerHooks;
+}
+/**
+ * The serializable subset of a {@link CMSModule} sent to the admin client.
+ * Excludes `config` (may hold adapter functions) and `serverHooks`.
+ *
+ * @public
+ */
+export interface CMSModuleDescriptor {
+    id: string;
+    label: LocalizedText;
+    icon: string;
+    context: ModuleContext;
+}
+/**
+ * Strips a {@link CMSModule} down to its serializable {@link CMSModuleDescriptor}
+ * for transport to the admin client. Drops `config` and `serverHooks`.
+ *
+ * @public
+ */
+export declare function toModuleDescriptor(module: CMSModule): CMSModuleDescriptor;