meno-core 1.0.48 → 1.0.49

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();
+    });
+  });
 });

package/lib/server/services/cmsService.ts

@@ -7,6 +7,7 @@ import type { CMSProvider, CMSSchemaInfo } from '../../shared/interfaces/content
 import type {
   CMSSchema,
   CMSItem,
+  CMSItemVersions,
   CMSRouteMatch,
   CMSListQuery,
   CMSFilterCondition,
@@ -30,6 +31,19 @@ interface CachedItems {
   timestamp: number;
 }
 
+export interface CMSServiceOptions {
+  /**
+   * When true, the SSR-facing read methods (`queryItems`, `getItemsByIds`,
+   * `matchRoute`) merge drafts over published content so the editor preview /
+   * dev server reflects unpublished edits. The editor management methods
+   * (`getItemVersions`, `listItemsWithDraftFlag`) keep strict published
+   * semantics regardless of this flag — they need to surface both versions
+   * separately. Static builds and production runtimes leave this off so
+   * deployed sites only ever serve published content.
+   */
+  previewMode?: boolean;
+}
+
 /**
  * CMS Service
  * Manages CMS schemas, route matching, and content querying
@@ -38,6 +52,7 @@ export class CMSService {
   private schemaCache = new Map<string, CMSSchemaInfo>();
   private routePatterns: RoutePattern[] = [];
   private provider?: CMSProvider;
+  private readonly previewMode: boolean;
 
   /** Item cache with TTL-based expiration */
   private itemsCache = new Map<string, CachedItems>();
@@ -47,9 +62,11 @@ export class CMSService {
   /**
    * Creates a new CMSService instance
    * @param provider - Optional CMSProvider for loading data (enables DI for testing)
+   * @param options - Service-level flags (preview mode for dev server)
    */
-  constructor(provider?: CMSProvider) {
+  constructor(provider?: CMSProvider, options: CMSServiceOptions = {}) {
     this.provider = provider;
+    this.previewMode = options.previewMode === true;
   }
 
   /**
@@ -62,9 +79,14 @@ export class CMSService {
   }
 
   /**
-   * Get items with caching
-   * Returns cached items if available and not expired, otherwise fetches fresh data
-   * Rich-text fields are automatically preprocessed to HTML for template interpolation
+   * Get items with caching, used by SSR-facing read methods.
+   *
+   * In preview mode (dev server) drafts are merged over published — drafts
+   * win on a per-`_filename` basis and draft-only items are included — so
+   * the editor preview reflects unpublished edits. Returns published-only
+   * otherwise. Rich-text fields are preprocessed to HTML for template
+   * interpolation either way.
+   *
    * @param collection - Collection ID to fetch items for
    * @returns Array of CMSItems with rich-text fields converted to HTML markers
    */
@@ -78,7 +100,21 @@ export class CMSService {
     }
 
     // Fetch fresh items
-    const rawItems = await this.provider!.getItems(collection);
+    let rawItems = await this.provider!.getItems(collection);
+
+    if (this.previewMode) {
+      const drafts = await this.provider!.getAllDrafts(collection);
+      if (drafts.length > 0) {
+        const byFilename = new Map<string, CMSItem>();
+        for (const item of rawItems) {
+          if (item._filename) byFilename.set(item._filename, item);
+        }
+        for (const draft of drafts) {
+          if (draft._filename) byFilename.set(draft._filename, draft);
+        }
+        rawItems = Array.from(byFilename.values());
+      }
+    }
 
     // Preprocess rich-text fields for template interpolation
     const items = this.preprocessRichTextFields(collection, rawItems);
@@ -405,6 +441,87 @@ export class CMSService {
    * Only clears items cache and provider cache before re-initializing.
    * Schema/route caches are swapped atomically inside initialize().
    */
+  // ----------------------------------------------------------------------
+  // Draft-version methods (Studio-only — never used by SSR / static export)
+  // ----------------------------------------------------------------------
+
+  /**
+   * Load both published and draft versions of an item, used by the editor.
+   * Returns `{}` when neither version exists.
+   */
+  async getItemVersions(collection: string, filename: string): Promise<CMSItemVersions> {
+    if (!this.provider) return {};
+    const [published, draft] = await Promise.all([
+      this.provider.getItemByFilename(collection, filename),
+      this.provider.getDraft(collection, filename),
+    ]);
+    const result: CMSItemVersions = {};
+    if (published) result.published = published;
+    if (draft) result.draft = draft;
+    return result;
+  }
+
+  /**
+   * List all items in a collection for the Studio item list:
+   * - Published items annotated with `_hasDraft: true` when a draft sibling exists.
+   * - Draft-only items (no published file yet) returned with `_isDraft: true`.
+   */
+  async listItemsWithDraftFlag(collection: string): Promise<CMSItem[]> {
+    if (!this.provider) return [];
+
+    const [published, drafts] = await Promise.all([
+      this.provider.getItems(collection),
+      this.provider.getAllDrafts(collection),
+    ]);
+
+    const draftFilenames = new Set(drafts.map(d => d._filename).filter(Boolean) as string[]);
+
+    const annotatedPublished: CMSItem[] = published.map(item => {
+      if (item._filename && draftFilenames.has(item._filename)) {
+        return { ...item, _hasDraft: true };
+      }
+      return item;
+    });
+
+    const publishedFilenames = new Set(published.map(i => i._filename).filter(Boolean) as string[]);
+    const draftOnly = drafts.filter(d => d._filename && !publishedFilenames.has(d._filename));
+
+    return [...annotatedPublished, ...draftOnly];
+  }
+
+  /** Pass-through to provider; no caching (drafts are read fresh in the editor). */
+  async getDraft(collection: string, filename: string): Promise<CMSItem | null> {
+    if (!this.provider) return null;
+    return this.provider.getDraft(collection, filename);
+  }
+
+  async hasDraft(collection: string, filename: string): Promise<boolean> {
+    if (!this.provider) return false;
+    return this.provider.hasDraft(collection, filename);
+  }
+
+  async saveDraft(collection: string, item: CMSItem): Promise<void> {
+    if (!this.provider) throw new Error('CMS provider not configured');
+    await this.provider.saveDraft(collection, item);
+    // Drafts don't enter the published items cache, but we invalidate it anyway
+    // so listItemsWithDraftFlag reflects the new draft on the next read.
+    this.itemsCache.delete(collection);
+  }
+
+  async discardDraft(collection: string, filename: string): Promise<void> {
+    if (!this.provider) throw new Error('CMS provider not configured');
+    await this.provider.discardDraft(collection, filename);
+    this.itemsCache.delete(collection);
+  }
+
+  async publishDraft(collection: string, filename: string): Promise<CMSItem> {
+    if (!this.provider) throw new Error('CMS provider not configured');
+    const item = await this.provider.publishDraft(collection, filename);
+    // Promotion changes the published file → invalidate cached items.
+    this.itemsCache.delete(collection);
+    return item;
+  }
+
   async refreshSchemas(): Promise<void> {
     if (!this.provider) {
       return;

package/lib/server/services/configService.ts

@@ -175,7 +175,12 @@ export class ConfigService {
 
     return {
       enabled: userScales.enabled ?? DEFAULT_RESPONSIVE_SCALES.enabled,
+      mode: (userScales as { mode?: 'breakpoints' | 'fluid' }).mode ?? DEFAULT_RESPONSIVE_SCALES.mode,
       baseReference: userScales.baseReference ?? DEFAULT_RESPONSIVE_SCALES.baseReference,
+      fluidRange: (userScales as { fluidRange?: { min: number; max: number } }).fluidRange
+        ?? (DEFAULT_RESPONSIVE_SCALES.fluidRange ? { ...DEFAULT_RESPONSIVE_SCALES.fluidRange } : undefined),
+      siteMargin: (userScales as { siteMargin?: { min: number; max: number } }).siteMargin
+        ?? (DEFAULT_RESPONSIVE_SCALES.siteMargin ? { ...DEFAULT_RESPONSIVE_SCALES.siteMargin } : undefined),
       fontSize: this.mergeScaleCategory(
         userScales.fontSize as BreakpointScales | undefined,
         DEFAULT_RESPONSIVE_SCALES.fontSize

package/lib/server/ssr/attributeBuilder.ts

@@ -75,6 +75,47 @@ export function buildAttributes(props: Record<string, unknown>, exclude: string[
   return attrs.length > 0 ? ' ' + attrs.join(' ') : '';
 }
 
+/**
+ * Build the editor-only attribute string used by XRay and selection sync.
+ * Mirrors what client-side ComponentBuilder.ts writes via ref callbacks.
+ * Returns a leading-space-prefixed attribute string, or '' when there's
+ * nothing to emit (or no elementPath supplied).
+ */
+export function buildEditorAttrs(opts: {
+  elementPath?: number[];
+  cmsItemIndexPath?: number[];
+  cmsListPaths?: number[][];
+  componentContext?: string;
+  parentComponentName?: string;
+  isComponentRoot?: boolean;
+  isSlotContent?: boolean;
+  isCMSListContainer?: boolean;
+}): string {
+  const { elementPath } = opts;
+  if (!elementPath) return '';
+
+  const parts: string[] = [`data-element-path="${escapeHtml(elementPath.join(','))}"`];
+
+  if (opts.cmsItemIndexPath && opts.cmsItemIndexPath.length > 0) {
+    parts.push(`data-cms-item-index="${escapeHtml(opts.cmsItemIndexPath.join('.'))}"`);
+    if (opts.cmsListPaths && opts.cmsListPaths.length === opts.cmsItemIndexPath.length) {
+      const ctx = JSON.stringify({ itemIndexPath: opts.cmsItemIndexPath, listPaths: opts.cmsListPaths });
+      parts.push(`data-cms-context="${escapeHtml(ctx)}"`);
+    }
+  }
+
+  if (opts.isCMSListContainer) parts.push(`data-cms-list="true"`);
+  if (opts.isComponentRoot) parts.push(`data-component-root="true"`);
+  if (opts.parentComponentName) {
+    parts.push(`data-parent-component="${escapeHtml(opts.parentComponentName)}"`);
+  }
+  if (opts.componentContext && !opts.isSlotContent) {
+    parts.push(`data-component-context="${escapeHtml(opts.componentContext)}"`);
+  }
+
+  return ' ' + parts.join(' ');
+}
+
 /**
  * Convert a style object to inline CSS string
  * Handles CSS variables (--is-0: value) and regular properties