meno-core 1.0.47 → 1.0.49

package/lib/server/providers/fileSystemCMSProvider.ts

@@ -7,10 +7,12 @@ import { existsSync, readdirSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import type { CMSProvider, CMSSchemaInfo } from '../../shared/interfaces/contentProvider';
 import type { CMSSchema, CMSItem } from '../../shared/types';
-import { validateCMSItem } from '../../shared/validation/validators';
-import { isSafePathSegment, isValidIdentifier } from '../../shared/pathSecurity';
+import { validateCMSItem, validateCMSDraftItem } from '../../shared/validation/validators';
+import { isSafePathSegment, isValidIdentifier, isReservedDraftFilename, CMS_DRAFT_SUFFIX } from '../../shared/pathSecurity';
 import { readJsonFile, fileExists } from '../runtime';
 
+const DRAFT_FILE_SUFFIX = `${CMS_DRAFT_SUFFIX}.json`;
+
 /**
  * Load JSON file content from disk
  * Logs a warning if JSON parsing fails (helps debug malformed files)
@@ -28,14 +30,25 @@ async function loadJSONFile(filePath: string): Promise<unknown | null> {
 }
 
 /**
- * Normalize a raw CMS item by adding _slug and _filename fields
+ * Normalize a raw CMS item by adding _slug and _filename fields.
+ * If `isDraft` is true, also sets the transient `_isDraft` flag.
  */
-function normalizeItem(content: unknown, filename: string): CMSItem {
-  return {
+function normalizeItem(content: unknown, filename: string, isDraft = false): CMSItem {
+  const base: CMSItem = {
     ...content as CMSItem,
     _slug: filename,
     _filename: filename,
   };
+  if (isDraft) base._isDraft = true;
+  return base;
+}
+
+/**
+ * Strip transient fields that must never be persisted to disk.
+ */
+function stripTransient<T extends Record<string, unknown>>(item: T): Omit<T, '_slug' | '_isDraft' | '_hasDraft' | '_url'> {
+  const { _slug, _isDraft, _hasDraft, _url, ...rest } = item;
+  return rest;
 }
 
 /**
@@ -61,13 +74,16 @@ export class FileSystemCMSProvider implements CMSProvider {
   }
 
   /**
-   * Validate filename to prevent path traversal attacks
+   * Validate filename to prevent path traversal attacks and reserved-suffix collisions.
    * @throws Error if filename is invalid
    */
   private validateFilename(filename: string): void {
     if (!isSafePathSegment(filename)) {
       throw new Error(`Invalid filename: "${filename}". Filenames cannot contain path separators or traversal sequences.`);
     }
+    if (isReservedDraftFilename(filename)) {
+      throw new Error(`Invalid filename: "${filename}". The "${CMS_DRAFT_SUFFIX}" suffix is reserved for draft files.`);
+    }
   }
 
   /**
@@ -131,7 +147,8 @@ export class FileSystemCMSProvider implements CMSProvider {
     }
 
     const files = readdirSync(collectionDir);
-    const jsonFiles = files.filter(f => f.endsWith('.json'));
+    // Published items only — exclude `*.draft.json` files (draft-version siblings)
+    const jsonFiles = files.filter(f => f.endsWith('.json') && !f.endsWith(DRAFT_FILE_SUFFIX));
 
     const results = await Promise.all(
       jsonFiles.map(async file => {
@@ -241,27 +258,199 @@ export class FileSystemCMSProvider implements CMSProvider {
       mkdirSync(collectionDir, { recursive: true });
     }
 
-    // Remove internal _slug field before saving (keep _filename in file for persistence)
-    const { _slug, ...itemData } = item;
+    // Strip transient fields (_slug, _isDraft, _hasDraft, _url) before persisting
+    const itemData = stripTransient(item as Record<string, unknown>);
 
     const filePath = join(collectionDir, `${filename}.json`);
     await writeFile(filePath, JSON.stringify(itemData, null, 2), 'utf-8');
   }
 
   /**
-   * Delete item by filename (or slug for backward compat)
+   * Delete item by filename. Removes the published file AND any draft sibling.
    */
   async deleteItem(collection: string, filename: string): Promise<void> {
     this.validateCollection(collection);
     this.validateFilename(filename);
     const { unlink } = await import('fs/promises');
-    const filePath = join(this.cmsDir, collection, `${filename}.json`);
 
+    const publishedPath = join(this.cmsDir, collection, `${filename}.json`);
+    if (existsSync(publishedPath)) {
+      await unlink(publishedPath);
+    }
+
+    const draftPath = this.draftPath(collection, filename);
+    if (existsSync(draftPath)) {
+      await unlink(draftPath);
+    }
+  }
+
+  // ---- Draft helpers ----------------------------------------------------
+
+  private draftPath(collection: string, filename: string): string {
+    return join(this.cmsDir, collection, `${filename}${DRAFT_FILE_SUFFIX}`);
+  }
+
+  /**
+   * Get the draft version of an item, or null if no draft file exists.
+   * Drafts skip strict validation — they may be partial / WIP.
+   */
+  async getDraft(collection: string, filename: string): Promise<CMSItem | null> {
+    this.validateCollection(collection);
+    this.validateFilename(filename);
+    const filePath = this.draftPath(collection, filename);
+    const content = await loadJSONFile(filePath);
+
+    if (!content || typeof content !== 'object') {
+      return null;
+    }
+
+    return normalizeItem(content, filename, /*isDraft*/ true);
+  }
+
+  /**
+   * List all drafts in a collection. Used by the Studio item list to mark
+   * items that have an outstanding draft sibling (or are draft-only).
+   */
+  async getAllDrafts(collection: string): Promise<CMSItem[]> {
+    this.validateCollection(collection);
+    const collectionDir = join(this.cmsDir, collection);
+    if (!existsSync(collectionDir)) return [];
+
+    const files = readdirSync(collectionDir).filter(f => f.endsWith(DRAFT_FILE_SUFFIX));
+
+    const results = await Promise.all(
+      files.map(async file => {
+        const filePath = join(collectionDir, file);
+        const content = await loadJSONFile(filePath);
+        return { file, content };
+      })
+    );
+
+    const drafts: CMSItem[] = [];
+    for (const { file, content } of results) {
+      if (content && typeof content === 'object') {
+        const filename = file.slice(0, -DRAFT_FILE_SUFFIX.length);
+        drafts.push(normalizeItem(content, filename, /*isDraft*/ true));
+      }
+    }
+    return drafts;
+  }
+
+  async hasDraft(collection: string, filename: string): Promise<boolean> {
+    this.validateCollection(collection);
+    this.validateFilename(filename);
+    return existsSync(this.draftPath(collection, filename));
+  }
+
+  /**
+   * Save the draft version of an item. Loose validation — drafts may have
+   * missing required fields or partial data. Strict validation only runs at
+   * publish time. The item's `_filename` determines the target file.
+   */
+  async saveDraft(collection: string, item: CMSItem): Promise<void> {
+    this.validateCollection(collection);
+    const { writeFile } = await import('fs/promises');
+
+    const schemas = await this.getAllSchemas();
+    const schemaInfo = schemas.get(collection);
+    if (!schemaInfo) {
+      throw new Error(`Unknown collection: ${collection}`);
+    }
+
+    let filename: string;
+    if (item._filename) {
+      filename = item._filename;
+    } else {
+      const slugField = schemaInfo.schema.slugField;
+      const slugValue = item[slugField];
+      filename = typeof slugValue === 'string' ? slugValue : String(slugValue);
+    }
+
+    if (!filename || filename === '[object Object]') {
+      throw new Error('Missing _filename field. Drafts must have _filename set on creation.');
+    }
+
+    this.validateFilename(filename);
+
+    const collectionDir = join(this.cmsDir, collection);
+    if (!existsSync(collectionDir)) {
+      mkdirSync(collectionDir, { recursive: true });
+    }
+
+    const itemData = stripTransient(item as Record<string, unknown>);
+
+    // Loose validation — drafts may be partial WIP. Strict validation
+    // (validateCMSItem) runs on Publish.
+    const validation = validateCMSDraftItem(itemData);
+    if (!validation.valid) {
+      const messages = validation.errors.map(e => `${e.path}: ${e.message}`).join(', ');
+      throw new Error(`Invalid draft: ${messages}`);
+    }
+
+    const filePath = this.draftPath(collection, filename);
+    await writeFile(filePath, JSON.stringify(itemData, null, 2), 'utf-8');
+  }
+
+  /**
+   * Discard the draft version of an item. No-op if no draft exists.
+   */
+  async discardDraft(collection: string, filename: string): Promise<void> {
+    this.validateCollection(collection);
+    this.validateFilename(filename);
+    const { unlink } = await import('fs/promises');
+    const filePath = this.draftPath(collection, filename);
     if (existsSync(filePath)) {
       await unlink(filePath);
     }
   }
 
+  /**
+   * Promote a draft to published. Reads `{filename}.draft.json`, writes the
+   * content to `{filename}.json`, then unlinks the draft. The published write
+   * happens first so a crash mid-operation leaves a valid published file plus
+   * an orphan draft (recoverable via the editor's Discard button) — never a
+   * gap with no published content.
+   *
+   * Throws if no draft exists.
+   */
+  async publishDraft(collection: string, filename: string): Promise<CMSItem> {
+    this.validateCollection(collection);
+    this.validateFilename(filename);
+    const { writeFile, unlink } = await import('fs/promises');
+
+    const draftFilePath = this.draftPath(collection, filename);
+    const content = await loadJSONFile(draftFilePath);
+    if (!content || typeof content !== 'object') {
+      throw new Error(`No draft to publish for ${collection}/${filename}`);
+    }
+
+    // Strict validation when going live
+    const item = normalizeItem(content, filename);
+    const validation = validateCMSItem(item);
+    if (!validation.valid) {
+      const messages = validation.errors.map(e => `${e.path}: ${e.message}`).join(', ');
+      throw new Error(`Cannot publish invalid draft: ${messages}`);
+    }
+
+    const collectionDir = join(this.cmsDir, collection);
+    if (!existsSync(collectionDir)) {
+      mkdirSync(collectionDir, { recursive: true });
+    }
+
+    const itemData = stripTransient(validation.data as unknown as Record<string, unknown>);
+    const publishedPath = join(collectionDir, `${filename}.json`);
+    await writeFile(publishedPath, JSON.stringify(itemData, null, 2), 'utf-8');
+
+    // Published written successfully — now retire the draft. If unlink fails,
+    // the published copy is already in place; an orphan draft can be cleared
+    // via the editor's Discard action.
+    if (existsSync(draftFilePath)) {
+      await unlink(draftFilePath);
+    }
+
+    return normalizeItem(itemData, filename);
+  }
+
   /**
    * Clear schema cache (useful when pages are modified)
    */

package/lib/server/routes/api/variables.ts

@@ -5,7 +5,8 @@
 
 import { variableService } from '../../services/VariableService';
 import { generateVariablesCSS } from '../../cssGenerator';
-import { loadBreakpointConfig, loadResponsiveScalesConfig } from '../../jsonLoader';
+import { loadBreakpointConfig } from '../../jsonLoader';
+import { configService } from '../../services/configService';
 import { jsonResponse } from './shared';
 
 /**
@@ -22,9 +23,10 @@ export async function handleVariablesStatusRoute(): Promise<Response> {
  * Returns generated CSS custom properties from variables.json
  */
 export async function handleVariablesCSSRoute(): Promise<Response> {
+  await configService.load();
   const variablesConfig = await variableService.loadConfig();
   const breakpointConfig = await loadBreakpointConfig();
-  const responsiveScalesConfig = await loadResponsiveScalesConfig();
+  const responsiveScalesConfig = configService.getResponsiveScales();
   const css = generateVariablesCSS(variablesConfig, breakpointConfig, responsiveScalesConfig);
   return new Response(css, {
     headers: { 'Content-Type': 'text/css' }

package/lib/server/routes/index.ts

@@ -141,7 +141,7 @@ export async function handleRoutes(
 
     // Page routes (SSR)
     if (url.pathname === '/' || (url.pathname.startsWith('/') && !url.pathname.includes('.'))) {
-      const response = await handlePageRoute(url, context);
+      const response = await handlePageRoute(url, context, req);
       logResponseTime(startTime, req);
       return response;
     }

package/lib/server/routes/pages.ts

@@ -15,15 +15,23 @@ import { generateErrorPage } from '../ssr/errorOverlay';
 import { cacheScript, hashContent } from '../scriptCache';
 import { readTextFile, fileExists, serveFile } from '../runtime';
 
+/** HTTP header sent by the studio's /__static__/ proxy to flag editor-preview requests. */
+const EDITOR_HEADER = 'x-meno-editor';
+
 /**
  * Handle page route requests
  */
 export async function handlePageRoute(
   url: URL,
-  context: RouteContext
+  context: RouteContext,
+  req?: Request
 ): Promise<Response | undefined> {
   const { pageService, componentService, cmsService, injectLiveReload, isEditor, serverPort } = context;
   const pagePath = url.pathname;
+  // Editor selection attributes (data-element-path, data-cms-context, ...) are emitted
+  // only when the request is proxied from the studio editor (it sets `x-meno-editor: 1`).
+  // Direct access to the SSR preview server (e.g., http://localhost:8082/) gets clean output.
+  const injectEditorAttrs = req?.headers.get(EDITOR_HEADER) === '1';
 
   // Load i18n config for locale extraction
   const i18nConfig = await loadI18nConfig();
@@ -40,6 +48,16 @@ export async function handlePageRoute(
     const cmsMatch = await cmsService.matchRoute(pathWithoutLocale, locale);
 
     if (cmsMatch) {
+      // Editor-only draft preview: when the studio editor requests a CMS page
+      // with `?previewDraft=1` and a draft exists for that item, swap the
+      // matched item for the draft. SSR continues to render normally; the
+      // live site (no editor header, no query param) is unaffected.
+      if (injectEditorAttrs && url.searchParams.get('previewDraft') === '1' && cmsMatch.item._filename) {
+        const draft = await cmsService.getDraft(cmsMatch.collection, cmsMatch.item._filename);
+        if (draft) {
+          cmsMatch.item = draft;
+        }
+      }
       // Load template page content by file path
       const templatePageContent = await loadPageByFilePath(cmsMatch.pagePath);
 
@@ -79,6 +97,7 @@ export async function handlePageRoute(
               pageLibraries: typedPageData.meta?.libraries,
             pageCustomCode: typedPageData.meta?.customCode,
               injectLiveReload,
+              injectEditorAttrs,
               isEditor,
               serverPort,
               returnSeparateJS: true,
@@ -115,6 +134,7 @@ export async function handlePageRoute(
             cmsTemplatePath,
             pageLibraries: typedPageData.meta?.libraries,
             pageCustomCode: typedPageData.meta?.customCode,
+            injectEditorAttrs,
             isEditor,
           });
 
@@ -200,6 +220,7 @@ export async function handlePageRoute(
           pageLibraries: pageData.meta?.libraries,
         pageCustomCode: pageData.meta?.customCode,
           injectLiveReload,
+          injectEditorAttrs,
           isEditor,
           serverPort,
           returnSeparateJS: true,
@@ -234,6 +255,7 @@ export async function handlePageRoute(
         cmsService,
         pageLibraries: pageData.meta?.libraries,
         pageCustomCode: pageData.meta?.customCode,
+        injectEditorAttrs,
         isEditor,
       });
 

package/lib/server/services/cmsService.test.ts

@@ -122,6 +122,13 @@ describe('CMSService', () => {
       },
       saveItem: async () => {},
       deleteItem: async () => {},
+      // Draft methods — overridden per test where needed; default stubs
+      getDraft: async () => null,
+      getAllDrafts: async () => [],
+      hasDraft: async () => false,
+      saveDraft: async () => {},
+      discardDraft: async () => {},
+      publishDraft: async () => { throw new Error('publishDraft not implemented in default mock'); },
     };
     service = new CMSService(mockProvider);
     await service.initialize();
@@ -641,6 +648,12 @@ describe('CMSService', () => {
         getItemById: async () => null,
         saveItem: async () => {},
         deleteItem: async () => {},
+        getDraft: async () => null,
+        getAllDrafts: async () => [],
+        hasDraft: async () => false,
+        saveDraft: async () => {},
+        discardDraft: async () => {},
+        publishDraft: async () => { throw new Error('not implemented'); },
       };
 
       const richService = new CMSService(richTextProvider);
@@ -690,6 +703,12 @@ describe('CMSService', () => {
         getItemById: async () => null,
         saveItem: async () => {},
         deleteItem: async () => {},
+        getDraft: async () => null,
+        getAllDrafts: async () => [],
+        hasDraft: async () => false,
+        saveDraft: async () => {},
+        discardDraft: async () => {},
+        publishDraft: async () => { throw new Error('not implemented'); },
       };
 
       const svc = new CMSService(provider);
@@ -729,6 +748,12 @@ describe('CMSService', () => {
         getItemById: async () => null,
         saveItem: async () => {},
         deleteItem: async () => {},
+        getDraft: async () => null,
+        getAllDrafts: async () => [],
+        hasDraft: async () => false,
+        saveDraft: async () => {},
+        discardDraft: async () => {},
+        publishDraft: async () => { throw new Error('not implemented'); },
       };
 
       const svc = new CMSService(provider);
@@ -767,6 +792,12 @@ describe('CMSService', () => {
         getItemById: async () => null,
         saveItem: async () => {},
         deleteItem: async () => {},
+        getDraft: async () => null,
+        getAllDrafts: async () => [],
+        hasDraft: async () => false,
+        saveDraft: async () => {},
+        discardDraft: async () => {},
+        publishDraft: async () => { throw new Error('not implemented'); },
       };
 
       const svc = new CMSService(provider);
@@ -777,4 +808,219 @@ describe('CMSService', () => {
       expect(items[1].content).toBeUndefined();
     });
   });
+
+  describe('drafts', () => {
+    function makeService(opts: {
+      published?: CMSItem[];
+      drafts?: CMSItem[];
+    }): CMSService {
+      const published = opts.published ?? [];
+      const drafts = opts.drafts ?? [];
+      const findByFilename = (list: CMSItem[], f: string) =>
+        list.find(i => i._filename === f) || null;
+
+      const provider: CMSProvider = {
+        getAllSchemas: async () => new Map([['blog-posts', mockSchemaInfo]]),
+        getItems: async () => published,
+        getItemBySlug: async (_c, s) => findByFilename(published, s),
+        getItemByFilename: async (_c, f) => findByFilename(published, f),
+        getItemById: async (_c, id) => published.find(i => i._id === id) ?? null,
+        saveItem: async () => {},
+        deleteItem: async () => {},
+        getDraft: async (_c, f) => findByFilename(drafts, f),
+        getAllDrafts: async () => drafts,
+        hasDraft: async (_c, f) => drafts.some(d => d._filename === f),
+        saveDraft: async () => {},
+        discardDraft: async () => {},
+        publishDraft: async (_c, f) => {
+          const d = findByFilename(drafts, f);
+          if (!d) throw new Error('no draft');
+          return { ...d, _isDraft: undefined };
+        },
+      };
+      const s = new CMSService(provider);
+      return s;
+    }
+
+    it('getItemVersions returns published + draft when both exist', async () => {
+      const svc = makeService({
+        published: [{ _id: '1', _filename: 'hello', slug: 'hello', title: 'Hello' }],
+        drafts: [{ _id: '1', _filename: 'hello', slug: 'hello', title: 'Hello (WIP)', _isDraft: true }],
+      });
+      await svc.initialize();
+      const versions = await svc.getItemVersions('blog-posts', 'hello');
+      expect(versions.published?.title).toBe('Hello');
+      expect(versions.draft?.title).toBe('Hello (WIP)');
+    });
+
+    it('getItemVersions returns draft-only when no published file exists', async () => {
+      const svc = makeService({
+        published: [],
+        drafts: [{ _id: 'new', _filename: 'brand-new', slug: 'brand-new', title: 'New', _isDraft: true }],
+      });
+      await svc.initialize();
+      const versions = await svc.getItemVersions('blog-posts', 'brand-new');
+      expect(versions.published).toBeUndefined();
+      expect(versions.draft?.title).toBe('New');
+    });
+
+    it('listItemsWithDraftFlag annotates published items that have drafts', async () => {
+      const svc = makeService({
+        published: [
+          { _id: '1', _filename: 'hello', slug: 'hello', title: 'Hello' },
+          { _id: '2', _filename: 'second', slug: 'second', title: 'Second' },
+        ],
+        drafts: [
+          { _id: '1', _filename: 'hello', slug: 'hello', title: 'Hello (WIP)', _isDraft: true },
+        ],
+      });
+      await svc.initialize();
+      const list = await svc.listItemsWithDraftFlag('blog-posts');
+      expect(list).toHaveLength(2);
+      const hello = list.find(i => i._filename === 'hello');
+      const second = list.find(i => i._filename === 'second');
+      expect(hello?._hasDraft).toBe(true);
+      expect(second?._hasDraft).toBeUndefined();
+    });
+
+    it('listItemsWithDraftFlag includes draft-only items at end', async () => {
+      const svc = makeService({
+        published: [{ _id: '1', _filename: 'hello', slug: 'hello', title: 'Hello' }],
+        drafts: [
+          { _id: 'new', _filename: 'brand-new', slug: 'brand-new', title: 'New', _isDraft: true },
+        ],
+      });
+      await svc.initialize();
+      const list = await svc.listItemsWithDraftFlag('blog-posts');
+      expect(list).toHaveLength(2);
+      const draftOnly = list.find(i => i._filename === 'brand-new');
+      expect(draftOnly?._isDraft).toBe(true);
+    });
+
+    it('queryItems is unaffected by drafts (still published-only)', async () => {
+      const svc = makeService({
+        published: [{ _id: '1', _filename: 'hello', slug: 'hello', title: 'Hello' }],
+        drafts: [
+          { _id: 'new', _filename: 'brand-new', slug: 'brand-new', title: 'New', _isDraft: true },
+        ],
+      });
+      await svc.initialize();
+      const items = await svc.queryItems({ collection: 'blog-posts' });
+      expect(items).toHaveLength(1);
+      expect(items[0]._filename).toBe('hello');
+    });
+
+    it('publishDraft delegates to provider and invalidates cache', async () => {
+      const svc = makeService({
+        published: [],
+        drafts: [{ _id: 'new', _filename: 'brand-new', slug: 'brand-new', title: 'New', _isDraft: true }],
+      });
+      await svc.initialize();
+      const result = await svc.publishDraft('blog-posts', 'brand-new');
+      expect(result.title).toBe('New');
+    });
+  });
+
+  describe('preview mode', () => {
+    function makeService(opts: {
+      previewMode?: boolean;
+      published?: CMSItem[];
+      drafts?: CMSItem[];
+    }): CMSService {
+      const published = opts.published ?? [];
+      const drafts = opts.drafts ?? [];
+      const findByFilename = (list: CMSItem[], f: string) =>
+        list.find(i => i._filename === f) || null;
+
+      const provider: CMSProvider = {
+        getAllSchemas: async () => new Map([['blog-posts', mockSchemaInfo]]),
+        getItems: async () => published,
+        getItemBySlug: async (_c, s) => findByFilename(published, s),
+        getItemByFilename: async (_c, f) => findByFilename(published, f),
+        getItemById: async (_c, id) => published.find(i => i._id === id) ?? null,
+        saveItem: async () => {},
+        deleteItem: async () => {},
+        getDraft: async (_c, f) => findByFilename(drafts, f),
+        getAllDrafts: async () => drafts,
+        hasDraft: async (_c, f) => drafts.some(d => d._filename === f),
+        saveDraft: async () => {},
+        discardDraft: async () => {},
+        publishDraft: async () => { throw new Error('not used'); },
+      };
+      return new CMSService(provider, { previewMode: opts.previewMode });
+    }
+
+    it('queryItems merges drafts over published when previewMode is true', async () => {
+      const svc = makeService({
+        previewMode: true,
+        published: [{ _id: '1', _filename: 'hello', slug: 'hello', title: 'Hello' }],
+        drafts: [{ _id: '1', _filename: 'hello', slug: 'hello', title: 'Hello (WIP)', _isDraft: true }],
+      });
+      await svc.initialize();
+      const items = await svc.queryItems({ collection: 'blog-posts' });
+      expect(items).toHaveLength(1);
+      expect(items[0].title).toBe('Hello (WIP)');
+      expect(items[0]._isDraft).toBe(true);
+    });
+
+    it('queryItems includes draft-only items in preview mode', async () => {
+      const svc = makeService({
+        previewMode: true,
+        published: [{ _id: '1', _filename: 'hello', slug: 'hello', title: 'Hello' }],
+        drafts: [{ _id: 'new', _filename: 'brand-new', slug: 'brand-new', title: 'Draft Only', _isDraft: true }],
+      });
+      await svc.initialize();
+      const items = await svc.queryItems({ collection: 'blog-posts' });
+      expect(items).toHaveLength(2);
+      expect(items.find(i => i._filename === 'brand-new')?._isDraft).toBe(true);
+    });
+
+    it('getItemsByIds merges drafts in preview mode', async () => {
+      const svc = makeService({
+        previewMode: true,
+        published: [{ _id: '1', _filename: 'hello', slug: 'hello', title: 'Hello' }],
+        drafts: [{ _id: '1', _filename: 'hello', slug: 'hello', title: 'Hello (WIP)', _isDraft: true }],
+      });
+      await svc.initialize();
+      const items = await svc.getItemsByIds('blog-posts', ['hello']);
+      expect(items[0]?.title).toBe('Hello (WIP)');
+      expect(items[0]?._isDraft).toBe(true);
+    });
+
+    it('preview mode does not affect editor management endpoints', async () => {
+      // getItemVersions and listItemsWithDraftFlag must keep strict
+      // published/draft separation regardless of previewMode — the editor
+      // needs to surface both versions individually.
+      const svc = makeService({
+        previewMode: true,
+        published: [{ _id: '1', _filename: 'hello', slug: 'hello', title: 'Hello' }],
+        drafts: [{ _id: '1', _filename: 'hello', slug: 'hello', title: 'Hello (WIP)', _isDraft: true }],
+      });
+      await svc.initialize();
+      const versions = await svc.getItemVersions('blog-posts', 'hello');
+      expect(versions.published?.title).toBe('Hello');
+      expect(versions.published?._isDraft).toBeUndefined();
+      expect(versions.draft?.title).toBe('Hello (WIP)');
+
+      const list = await svc.listItemsWithDraftFlag('blog-posts');
+      const item = list.find(i => i._filename === 'hello');
+      expect(item?.title).toBe('Hello');
+      expect(item?._hasDraft).toBe(true);
+    });
+
+    it('default (production) mode keeps queryItems published-only', async () => {
+      const svc = makeService({
+        published: [{ _id: '1', _filename: 'hello', slug: 'hello', title: 'Hello' }],
+        drafts: [
+          { _id: '1', _filename: 'hello', slug: 'hello', title: 'Hello (WIP)', _isDraft: true },
+          { _id: 'new', _filename: 'brand-new', slug: 'brand-new', title: 'Draft Only', _isDraft: true },
+        ],
+      });
+      await svc.initialize();
+      const items = await svc.queryItems({ collection: 'blog-posts' });
+      expect(items).toHaveLength(1);
+      expect(items[0].title).toBe('Hello');
+      expect(items[0]._isDraft).toBeUndefined();
+    });
+  });
 });