meno-core 1.0.53 → 1.0.54

package/lib/shared/treePathUtils.ts

@@ -2,7 +2,7 @@
  * Tree path utilities for parsing and navigating tree structure paths
  */
 
-import { ComponentNode, PageData, JSONPage } from './types';
+import { type ComponentNode, type PageData, JSONPage } from './types';
 import type { PropDefinition } from './types';
 import type { Path } from './pathArrayUtils';
 import { stringToPath } from './pathArrayUtils';
@@ -28,12 +28,12 @@ export interface NodeLocation {
  */
 export function validateComponentStructure(pageData: PageData | null): boolean {
   if (!pageData) return false;
-  
+
   // Check for page format (has root property)
   if ('root' in pageData && pageData.root) {
     return true;
   }
-  
+
   // Check for component format (has component.structure property)
   if ('component' in pageData && pageData.component) {
     if ('structure' in pageData.component && pageData.component.structure) {
@@ -42,7 +42,7 @@ export function validateComponentStructure(pageData: PageData | null): boolean {
     // Component exists but structure is missing
     return false;
   }
-  
+
   return false;
 }
 
@@ -52,12 +52,12 @@ export function validateComponentStructure(pageData: PageData | null): boolean {
  */
 export function getRootData(pageData: PageData | null): ComponentNode | null {
   if (!pageData) return null;
-  
+
   // Check for page format (has root property)
   if ('root' in pageData && pageData.root) {
     return pageData.root;
   }
-  
+
   // Check for component format (has component.structure property)
   if ('component' in pageData && pageData.component) {
     if ('structure' in pageData.component) {
@@ -70,7 +70,7 @@ export function getRootData(pageData: PageData | null): ComponentNode | null {
       // Component exists but structure field is missing
     }
   }
-  
+
   return null;
 }
 
@@ -79,10 +79,7 @@ export function getRootData(pageData: PageData | null): ComponentNode | null {
  * Handles paths like: root_0, root_0_children_0, root_0_children_0_children_1
  * Also accepts array paths: [0], [0,0], [0,0,1]
  */
-export function getParentAndIndexFromPath(
-  path: Path | string, 
-  pageData: PageData
-): NodeLocation | null {
+export function getParentAndIndexFromPath(path: Path | string, pageData: PageData): NodeLocation | null {
   const rootData = getRootData(pageData);
   if (!rootData) return null;
 
@@ -94,7 +91,7 @@ export function getParentAndIndexFromPath(
     return {
       parent: pageData,
       index: 0,
-      node: rootData
+      node: rootData,
     };
   }
 
@@ -107,25 +104,25 @@ export function getParentAndIndexFromPath(
   for (let i = 1; i < pathArray.length; i++) {
     const childIndex = pathArray[i];
 
-      if (!current || !('children' in current) || !Array.isArray(current.children)) {
-        return null;
-      }
-      
-      if (isNaN(childIndex) || childIndex < 0 || childIndex >= current.children.length) {
-        return null;
-      }
+    if (!current || !('children' in current) || !Array.isArray(current.children)) {
+      return null;
+    }
+
+    if (isNaN(childIndex) || childIndex < 0 || childIndex >= current.children.length) {
+      return null;
+    }
 
     parent = current;
-      const child = current.children[childIndex];
-      if (typeof child === 'string') {
-        return null;
-      }
-      current = child;
-      lastIndex = childIndex;
+    const child = current.children[childIndex];
+    if (typeof child === 'string') {
+      return null;
+    }
+    current = child;
+    lastIndex = childIndex;
 
-      // If this is the last navigation step, we found our node
+    // If this is the last navigation step, we found our node
     if (i === pathArray.length - 1) {
-        return { parent, index: childIndex, node: current };
+      return { parent, index: childIndex, node: current };
     }
   }
 
@@ -141,7 +138,9 @@ export function getParentAndIndexFromPath(
  * Extract structure without styles/props for tree comparison
  * This allows tree to only regenerate when structure changes, not styles
  */
-export function extractStructureWithoutStyles(node: ComponentNode | string | null | undefined): ComponentNode | string | null | undefined {
+export function extractStructureWithoutStyles(
+  node: ComponentNode | string | null | undefined,
+): ComponentNode | string | null | undefined {
   if (!node || typeof node === 'string') {
     return node;
   }
@@ -157,13 +156,13 @@ export function extractStructureWithoutStyles(node: ComponentNode | string | nul
   const component = 'component' in node ? (node as any).component : undefined;
   const ifCondition = 'if' in node ? node.if : undefined;
   const children = 'children' in node ? node.children : undefined;
-  
+
   // Recursively process children
   let processedChildren: ComponentNode | (ComponentNode | string)[] | string | undefined;
   if (children) {
     if (Array.isArray(children)) {
       processedChildren = children.map((child: ComponentNode | string) =>
-        typeof child === 'string' ? child : extractStructureWithoutStyles(child) as ComponentNode
+        typeof child === 'string' ? child : (extractStructureWithoutStyles(child) as ComponentNode),
       );
     } else if (typeof children === 'string') {
       processedChildren = children;
@@ -202,7 +201,7 @@ export function calculateInsertionIndex(
     linearIndex?: number;
   },
   parentChildren: Array<ComponentNode | string>,
-  nodeDataMap: Map<string, ComponentNode | string>
+  nodeDataMap: Map<string, ComponentNode | string>,
 ): number {
   if (target.childIndex !== undefined && target.childIndex >= 0) {
     // Most reliable: use childIndex directly
@@ -250,13 +249,13 @@ export function isValidNodeLocation(location: unknown): location is NodeLocation
   if (!location || typeof location !== 'object') {
     return false;
   }
-  
+
   // Use proper type narrowing instead of assertion
   const loc = location as Record<string, unknown>;
   const hasParent = 'parent' in loc && (loc.parent === null || typeof loc.parent === 'object');
   const hasIndex = 'index' in loc && typeof loc.index === 'number' && loc.index >= 0;
   const hasNode = 'node' in loc && (loc.node === null || typeof loc.node === 'object');
-  
+
   return hasParent && hasIndex && hasNode;
 }
 
@@ -267,7 +266,7 @@ export function isValidPath(path: unknown): path is Path {
   if (!Array.isArray(path)) {
     return false;
   }
-  
+
   // Path is an array of numbers
   return path.every((item): item is number => typeof item === 'number' && item >= 0);
 }
@@ -275,28 +274,24 @@ export function isValidPath(path: unknown): path is Path {
 /**
  * Type guard to check if parent is PageData
  */
-export function isPageDataParent(
-  parent: ComponentNode | PageData | null
-): parent is PageData {
+export function isPageDataParent(parent: ComponentNode | PageData | null): parent is PageData {
   if (!parent) return false;
-  
+
   // Check for JSONPage format (has root property)
   if ('root' in parent) return true;
-  
+
   // Check for component format - component must be an object, not a string
   if ('component' in parent) {
     return typeof parent.component === 'object' && parent.component !== null;
   }
-  
+
   return false;
 }
 
 /**
  * Type guard to check if parent is ComponentNode
  */
-export function isComponentNodeParent(
-  parent: ComponentNode | PageData | null
-): parent is ComponentNode {
+export function isComponentNodeParent(parent: ComponentNode | PageData | null): parent is ComponentNode {
   if (!parent) return false;
   // Check for 'type' property (all ComponentNodes have it)
   // Then check for specific node types that can have children:
@@ -307,28 +302,29 @@ export function isComponentNodeParent(
   // - EmbedNode: type === 'embed'
   // - ListNode: type === 'list' (also handles legacy 'cms-list' for migration)
   const nodeType = (parent as any).type;
-  return 'type' in parent && (
-    'tag' in parent ||
-    'component' in parent ||
-    nodeType === 'slot' ||
-    nodeType === 'link' ||
-    nodeType === 'embed' ||
-    nodeType === 'cms-list' ||  // Legacy support for migration
-    nodeType === 'list'
+  return (
+    'type' in parent &&
+    ('tag' in parent ||
+      'component' in parent ||
+      nodeType === 'slot' ||
+      nodeType === 'link' ||
+      nodeType === 'embed' ||
+      nodeType === 'cms-list' || // Legacy support for migration
+      nodeType === 'list')
   );
 }
 
 /**
  * Get children array from parent (handles both PageData and ComponentNode)
  */
-export function getParentChildren(
-  parent: ComponentNode | PageData | null
-): Array<ComponentNode | string> | null {
+export function getParentChildren(parent: ComponentNode | PageData | null): Array<ComponentNode | string> | null {
   if (!parent) return null;
-  
+
   if (isPageDataParent(parent)) {
     const rootData = getRootData(parent);
-    return rootData && 'children' in rootData ? (rootData.children as Array<ComponentNode | string> | undefined) || null : null;
+    return rootData && 'children' in rootData
+      ? (rootData.children as Array<ComponentNode | string> | undefined) || null
+      : null;
   }
 
   if (isComponentNodeParent(parent)) {
@@ -343,10 +339,10 @@ export function getParentChildren(
  */
 export function setParentChildren(
   parent: ComponentNode | PageData | null,
-  children: Array<ComponentNode | string>
+  children: Array<ComponentNode | string>,
 ): void {
   if (!parent) return;
-  
+
   if (isPageDataParent(parent)) {
     const rootData = getRootData(parent);
     if (rootData && 'children' in rootData) {
@@ -358,4 +354,3 @@ export function setParentChildren(
     }
   }
 }
-

package/lib/shared/types/api.ts

@@ -18,7 +18,7 @@ export interface HMRMessage {
     | 'hmr:cms-collections-update'
     | 'hmr:config-update';
   path?: string;
-  collection?: string;  // For CMS updates
+  collection?: string; // For CMS updates
 }
 
 export interface PageListResponse {
@@ -84,4 +84,3 @@ export interface PageMetaData {
   /** Custom code injected into head/body for this page */
   customCode?: CustomCodeConfig;
 }
-

package/lib/shared/types/cms.ts

@@ -5,15 +5,15 @@
 
 /** Field types supported by CMS */
 export type CMSFieldType =
-  | 'string'     // Single-line text (auto-localizable when project has multiple locales)
-  | 'text'       // Multi-line text (auto-localizable when project has multiple locales)
-  | 'rich-text'  // Rich text with formatting (auto-localizable when project has multiple locales)
-  | 'number'     // Numeric value
-  | 'boolean'    // True/false
-  | 'image'      // Image URL/path
-  | 'file'       // File URL/path (any file type)
-  | 'date'       // ISO date string
-  | 'select'     // Single selection from options
+  | 'string' // Single-line text (auto-localizable when project has multiple locales)
+  | 'text' // Multi-line text (auto-localizable when project has multiple locales)
+  | 'rich-text' // Rich text with formatting (auto-localizable when project has multiple locales)
+  | 'number' // Numeric value
+  | 'boolean' // True/false
+  | 'image' // Image URL/path
+  | 'file' // File URL/path (any file type)
+  | 'date' // ISO date string
+  | 'select' // Single selection from options
   | 'reference'; // Reference to another collection item
 
 /** Single field definition in a schema */
@@ -21,12 +21,12 @@ export interface CMSFieldDefinition {
   type: CMSFieldType;
   required?: boolean;
   default?: unknown;
-  label?: string;           // Display label in editor
-  description?: string;     // Help text
-  options?: string[];       // For 'select' type
-  accept?: string;           // For 'file' type - MIME filter (e.g. "application/pdf", "*/*")
-  collection?: string;      // For 'reference' type - target collection ID
-  multiple?: boolean;       // For 'reference' type - allows array of IDs
+  label?: string; // Display label in editor
+  description?: string; // Help text
+  options?: string[]; // For 'select' type
+  accept?: string; // For 'file' type - MIME filter (e.g. "application/pdf", "*/*")
+  collection?: string; // For 'reference' type - target collection ID
+  multiple?: boolean; // For 'reference' type - allows array of IDs
 }
 
 /** Data delivery strategy for client-side CMS data */
@@ -156,7 +156,7 @@ export interface CMSRouteMatch {
   collection: string;
   slug: string;
   item: CMSItem;
-  pagePath: string;  // Path to the template page file
+  pagePath: string; // Path to the template page file
 }
 
 /** Filter operators for CMS queries */
@@ -165,14 +165,14 @@ export type CMSFilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'co
 /** Single filter condition */
 export interface CMSFilterCondition {
   field: string;
-  operator?: CMSFilterOperator;  // defaults to 'eq'
+  operator?: CMSFilterOperator; // defaults to 'eq'
   value: unknown;
 }
 
 /** Sort configuration */
 export interface CMSSortConfig {
   field: string;
-  order?: 'asc' | 'desc';  // defaults to 'asc'
+  order?: 'asc' | 'desc'; // defaults to 'asc'
 }
 
 /** CMSList query configuration */
@@ -304,9 +304,13 @@ export function singularize(collection: string): string {
     return collection.slice(0, -3) + 'y';
   }
   // Handle -es for words ending in s, x, z, ch, sh
-  if (collection.endsWith('ses') || collection.endsWith('xes') ||
-      collection.endsWith('zes') || collection.endsWith('ches') ||
-      collection.endsWith('shes')) {
+  if (
+    collection.endsWith('ses') ||
+    collection.endsWith('xes') ||
+    collection.endsWith('zes') ||
+    collection.endsWith('ches') ||
+    collection.endsWith('shes')
+  ) {
     return collection.slice(0, -2);
   }
   // Simple rule: remove trailing 's' if present

package/lib/shared/types/comment.ts

@@ -10,12 +10,7 @@
  */
 
 /** Workflow status. No custom statuses for MVP. */
-export type CommentStatus =
-  | 'open'
-  | 'in-progress'
-  | 'ready-for-review'
-  | 'resolved'
-  | 'closed';
+export type CommentStatus = 'open' | 'in-progress' | 'ready-for-review' | 'resolved' | 'closed';
 
 export const COMMENT_STATUSES: readonly CommentStatus[] = [
   'open',
@@ -47,24 +42,62 @@ export interface CommentNodeIdentity {
 }
 
 /**
- * Where the pin attaches on the page. nodePath is positional; nodeIdentity
- * is used at render time to detect that the pin has been orphaned (Phase 4).
+ * One step of a {@link CommentAnchor.nodeRef}: a node addressed by its TYPE and
+ * its occurrence among same-type siblings, rather than its raw child index. E.g.
+ * `{ kind:'component', name:'HomeProducts', nth:0 }` = "the first HomeProducts
+ * under this parent". Move-invariant: reordering/inserting/deleting siblings of
+ * OTHER types doesn't change it (only reordering same-type instances does).
+ */
+export interface CommentNodeRefSegment {
+  kind: 'component' | 'node';
+  /** Component name (kind=component) or HTML tag / node type (kind=node). */
+  name: string;
+  /** 0-based occurrence among same-(kind,name) siblings under the same parent. */
+  nth: number;
+}
+
+/**
+ * Where the pin sits. Pins are ELEMENT-ANCHORED: a comment attaches to the
+ * specific node/component the user picked (exactly like a selection), not to a
+ * spot on the page. The anchor's source of truth is `nodeRef` — a type +
+ * occurrence path from the page root (e.g. `HomeProducts[0]` →
+ * `Section[2] > Heading[4]`) — so a pin survives the section being moved,
+ * inserted before, or its differently-typed siblings being deleted. `nodePath`
+ * is a create-time positional snapshot kept only as a fallback for legacy pins
+ * (no `nodeRef`). `cmsItemIndexPath` disambiguates which CMS-list copy was
+ * clicked. The pin is drawn over the resolved element's rect;
+ * `offsetXPercent`/`offsetYPercent` place it WITHIN that rect.
+ *
+ * The identity resolves to a DOM element in both the same-origin SSR canvas and
+ * the cross-origin Astro play DOM (nodeRef → live nodePath → existing x-ray
+ * pipeline), and survives the JSON→.astro migration. When the node can no longer
+ * be resolved the comment is "detached".
  */
 export interface CommentAnchor {
-  /** Path array into the page tree, e.g. [0, 1, 2]. */
+  /**
+   * Type + occurrence path from the page root — the move-resilient source of
+   * truth for the anchored node. Absent only on legacy pins (fall back to
+   * `nodePath`).
+   */
+  nodeRef?: CommentNodeRefSegment[];
+  /** Create-time positional snapshot of the anchored node (fallback for legacy pins). */
   nodePath: number[];
-  /** Identity fingerprint for orphan detection. */
+  /**
+   * CMS-list item path disambiguating which list copy the anchored element
+   * belongs to (parallel to SelectionStore's `selectedCMSItemIndexPath`).
+   * Absent when the element is not inside a CMS list.
+   */
+  cmsItemIndexPath?: number[];
+  /** Identity fingerprint of the anchored node, used to detect orphan pins. */
   nodeIdentity: CommentNodeIdentity;
-  /** Horizontal offset inside the component's bounding box, 0..1. */
+  /** Horizontal position WITHIN the anchored element's rect, 0..1 (default 0.5). */
   offsetXPercent: number;
-  /** Vertical offset inside the component's bounding box, 0..1. */
+  /** Vertical position WITHIN the anchored element's rect, 0..1 (default 0.5). */
   offsetYPercent: number;
   /**
    * Breakpoint frame this pin was placed on (e.g. `'base'`, `'tablet'`,
-   * `'mobile'`). Only set for pins created in Design Mode's multi-frame
-   * canvas, so the pin is only shown on the frame where it was pinned.
-   * When unset, the pin renders on every frame (single-frame / page mode,
-   * or pins created before this field existed).
+   * `'mobile'`). A pin is only shown on the frame where it was pinned. When
+   * unset, the pin renders on every frame (or pins created before this field).
    */
   breakpoint?: string;
 }

package/lib/shared/types/components.ts

@@ -24,18 +24,18 @@ export type EnumsConfig = Record<string, readonly string[]>;
  */
 export interface I18nValue {
   _i18n: true;
-  [locale: string]: string | unknown[] | true;  // true is for the _i18n marker, arrays for list props
+  [locale: string]: string | unknown[] | true; // true is for the _i18n marker, arrays for list props
 }
 
 /**
  * Locale configuration with metadata
  */
 export interface LocaleConfig {
-  code: string;        // URL prefix & translation key (e.g., "en", "pl")
-  name: string;        // English name for admin UI (e.g., "Polish")
-  nativeName: string;  // Native name for public UI (e.g., "Polski")
-  langTag: string;     // BCP 47 language tag for SEO (e.g., "pl-PL")
-  icon?: string;       // Optional flag icon path (e.g., "/icons/flag-en.svg")
+  code: string; // URL prefix & translation key (e.g., "en", "pl")
+  name: string; // English name for admin UI (e.g., "Polish")
+  nativeName: string; // Native name for public UI (e.g., "Polski")
+  langTag: string; // BCP 47 language tag for SEO (e.g., "pl-PL")
+  icon?: string; // Optional flag icon path (e.g., "/icons/flag-en.svg")
 }
 
 /**
@@ -66,10 +66,10 @@ export interface LinkPropValue {
 export interface BasePropDefinition {
   type: Exclude<PropType, 'list'>;
   default?: string | number | boolean | I18nValue | LinkPropValue;
-  options?: readonly string[];  // Required for "select" type (inline options)
-  enumName?: string;  // For "select" type: reference to project-level enum
-  accept?: string;  // For "file" type: MIME pattern like "image/*", "video/*"
-  editor?: 'basic' | 'extended';  // For 'rich-text' type: which editor to use
+  options?: readonly string[]; // Required for "select" type (inline options)
+  enumName?: string; // For "select" type: reference to project-level enum
+  accept?: string; // For "file" type: MIME pattern like "image/*", "video/*"
+  editor?: 'basic' | 'extended'; // For 'rich-text' type: which editor to use
 }
 
 /**
@@ -120,9 +120,9 @@ export function isBasePropDefinition(def: PropDefinition): def is BasePropDefini
 export interface StructuredComponentDefinition {
   interface?: Record<string, PropDefinition>;
   structure?: ComponentNode;
-  javascript?: string;  // Vanilla JS code to be rendered at end of HTML
-  css?: string;  // CSS code to be rendered in <style> tag in <head>
-  category?: string;  // Component category for organization
+  javascript?: string; // Vanilla JS code to be rendered at end of HTML
+  css?: string; // CSS code to be rendered in <style> tag in <head>
+  category?: string; // Component category for organization
   /**
    * Define which props are available as JavaScript variables (Astro-style define:vars)
    * - true: all props from interface are exposed
@@ -141,9 +141,9 @@ export interface StructuredComponentDefinition {
  * Supports both new format (just component) and legacy format (type/props/children/component)
  */
 export interface ComponentDefinition {
-  type?: string;  // Legacy format
-  props?: Record<string, unknown>;  // Legacy format
-  children?: unknown[];  // Legacy format
+  type?: string; // Legacy format
+  props?: Record<string, unknown>; // Legacy format
+  children?: unknown[]; // Legacy format
   component: StructuredComponentDefinition;
 }
 
@@ -168,15 +168,17 @@ export interface JSONPage {
 /**
  * Page data type that can be either a JSONPage or a component definition structure
  */
-export type PageData = JSONPage | {
-  component: {
-    structure?: ComponentNode;
-    interface?: Record<string, PropDefinition>;
-    javascript?: string;
-    css?: string;
-    acceptsStyles?: boolean;
-  }
-};
+export type PageData =
+  | JSONPage
+  | {
+      component: {
+        structure?: ComponentNode;
+        interface?: Record<string, PropDefinition>;
+        javascript?: string;
+        css?: string;
+        acceptsStyles?: boolean;
+      };
+    };
 
 /**
  * Page data with component structure (for type narrowing)

package/lib/shared/types/errors.test.ts

@@ -1,10 +1,5 @@
 import { describe, test, expect } from 'bun:test';
-import {
-  createValidationError,
-  createTypeSafetyError,
-  type ValidationError,
-  type TypeSafetyError,
-} from './errors';
+import { createValidationError, createTypeSafetyError, type ValidationError, type TypeSafetyError } from './errors';
 
 describe('error types', () => {
   describe('createValidationError', () => {

package/lib/shared/types/errors.ts

@@ -27,9 +27,7 @@ export interface TypeSafetyError extends Error {
  * Result type for operations that can fail
  * Replaces null returns with explicit success/failure
  */
-export type Result<T> =
-  | { success: true; data: T }
-  | { success: false; error: ValidationError };
+export type Result<T> = { success: true; data: T } | { success: false; error: ValidationError };
 
 /**
  * Create a validation error
@@ -40,7 +38,7 @@ export function createValidationError(
     path?: string;
     receivedValue?: unknown;
     expectedType?: string;
-  }
+  },
 ): ValidationError {
   return {
     message,
@@ -57,7 +55,7 @@ export function createTypeSafetyError(
     path?: string;
     receivedValue?: unknown;
     expectedType?: string;
-  }
+  },
 ): TypeSafetyError {
   const error = new Error(message) as TypeSafetyError;
   Object.defineProperty(error, 'path', { value: options?.path, writable: false });
@@ -65,5 +63,3 @@ export function createTypeSafetyError(
   Object.defineProperty(error, 'expectedType', { value: options?.expectedType, writable: false });
   return error;
 }
-
-