meno-core 1.0.52 → 1.0.54

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

@@ -0,0 +1,132 @@
+/**
+ * Comment / Pin Types
+ *
+ * Comments are Figma-style pins placed on components in the studio canvas.
+ * One file per pin (thread embedded). Storage layout (status as top folder):
+ *   {projectRoot}/comments/<status>/<pageSlug>--<seq>--<titleSlug>.json
+ *   e.g. comments/open/blog__post--3--hero-is-too-dark.json
+ *
+ * Pins are an authoring-time concept — they live in studio only.
+ */
+
+/** Workflow status. No custom statuses for MVP. */
+export type CommentStatus = 'open' | 'in-progress' | 'ready-for-review' | 'resolved' | 'closed';
+
+export const COMMENT_STATUSES: readonly CommentStatus[] = [
+  'open',
+  'in-progress',
+  'ready-for-review',
+  'resolved',
+  'closed',
+] as const;
+
+/** Identifies the GitHub user who authored a thread entry. */
+export interface CommentAuthor {
+  /** GitHub login. `"local"` for non-electron / unauthenticated runs. */
+  login: string;
+  name?: string;
+  avatarUrl?: string;
+}
+
+/**
+ * Identity fingerprint for the anchored node — used to detect orphan pins
+ * when the tree shifts. Mirrors the shape of `nodesMatch()` in NodeStore.
+ */
+export interface CommentNodeIdentity {
+  /** `'component'` or `'node'` (HTML). */
+  kind: 'component' | 'node';
+  /** Component name (when kind=component) or HTML tag (when kind=node). */
+  name: string;
+  /** Editor-set label, used to disambiguate same-type siblings. */
+  label?: string;
+}
+
+/**
+ * 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 {
+  /**
+   * 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[];
+  /**
+   * 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 position WITHIN the anchored element's rect, 0..1 (default 0.5). */
+  offsetXPercent: number;
+  /** 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'`). 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;
+}
+
+/** One message in a comment's thread (initial + replies). */
+export interface CommentThreadEntry {
+  id: string;
+  author: CommentAuthor;
+  /** ISO timestamp. */
+  createdAt: string;
+  text: string;
+  /** When this entry transitioned the comment status, the target status. */
+  statusChange: CommentStatus | null;
+}
+
+/** A pinned comment. */
+export interface Comment {
+  _id: string;
+  _filename: string;
+  /** Page path the pin lives on (e.g. `"blog/post"`). */
+  _pagePath: string;
+  /** Stable per-page badge number. Server assigns at create time. */
+  _seq: number;
+  /** ISO timestamps. */
+  _createdAt: string;
+  _updatedAt: string;
+  /** Git HEAD SHA captured at create time, or null when unavailable. */
+  _commitSha: string | null;
+  anchor: CommentAnchor;
+  status: CommentStatus;
+  thread: CommentThreadEntry[];
+}

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;
 }
-
-

package/lib/shared/types/experiments.ts

@@ -4,52 +4,52 @@
  */
 
 export interface ConversionGoal {
-  id: string
-  name: string
-  type: 'click' | 'navigation' | 'custom'
+  id: string;
+  name: string;
+  type: 'click' | 'navigation' | 'custom';
   /** CSS selector for click goals */
-  selector?: string
+  selector?: string;
   /** URL pattern for navigation goals */
-  url?: string
+  url?: string;
   /** Custom event name */
-  event?: string
+  event?: string;
 }
 
 export interface ExperimentVariant {
-  branch: string
+  branch: string;
   /** Percentage of traffic (0-100) */
-  weight: number
+  weight: number;
   /** Cloudflare Pages preview deploy URL, e.g. "https://variant-blue.project.pages.dev" */
-  deployUrl: string
+  deployUrl: string;
 }
 
 export interface Experiment {
-  id: string
-  name: string
-  status: 'draft' | 'running' | 'paused' | 'completed'
-  controlBranch: string
-  variants: ExperimentVariant[]
+  id: string;
+  name: string;
+  status: 'draft' | 'running' | 'paused' | 'completed';
+  controlBranch: string;
+  variants: ExperimentVariant[];
   /** Percentage of traffic for control (0-100) */
-  controlWeight: number
-  conversionGoals: ConversionGoal[]
-  createdAt: string
-  startedAt?: string
-  endedAt?: string
+  controlWeight: number;
+  conversionGoals: ConversionGoal[];
+  createdAt: string;
+  startedAt?: string;
+  endedAt?: string;
 }
 
 export interface ExperimentResults {
-  experimentId: string
-  variants: VariantResult[]
+  experimentId: string;
+  variants: VariantResult[];
 }
 
 export interface VariantResult {
-  variant: string
-  visitors: number
-  conversions: number
-  conversionRate: number
+  variant: string;
+  visitors: number;
+  conversions: number;
+  conversionRate: number;
   /** Lift percentage compared to control */
-  lift?: number
+  lift?: number;
   /** p-value from z-test */
-  pValue?: number
-  isSignificant: boolean
+  pValue?: number;
+  isSignificant: boolean;
 }

package/lib/shared/types/index.ts

@@ -1,7 +1,7 @@
 /**
  * Shared TypeScript types and interfaces
  * Used by both client and server code
- * 
+ *
  * This is the main entry point for all shared types.
  * Types are organized into separate files for better maintainability.
  */
@@ -173,5 +173,17 @@ export type {
   VariantResult,
 } from './experiments';
 
-// Note: Path types are exported from ../paths/index.ts, not from here
+// Comment / Pin types
+export type {
+  CommentStatus,
+  CommentAuthor,
+  CommentNodeIdentity,
+  CommentNodeRefSegment,
+  CommentAnchor,
+  CommentThreadEntry,
+  Comment,
+} from './comment';
 
+export { COMMENT_STATUSES } from './comment';
+
+// Note: Path types are exported from ../paths/index.ts, not from here

package/lib/shared/types/rendering.ts

@@ -57,6 +57,14 @@ export interface TemplateContext {
   props: Record<string, unknown>;
   /** Component definition (for variants, defaults) */
   componentDef?: ComponentDefinition | StructuredComponentDefinition;
+  /**
+   * Resolved props of the component that hosts this one (one level up).
+   * Layered into template evaluation at lower precedence than `props`, so a
+   * `{{x}}` in a child component's structure falls back to the parent's `x`
+   * when the child doesn't declare it. Aligned with `buildListResolutionScope`
+   * for list `items` / `filter` templates.
+   */
+  parentProps?: Record<string, unknown>;
   /** Future extension points (cms, page, etc.) */
   [namespace: string]: unknown;
 }

package/lib/shared/types/styles.ts

@@ -80,4 +80,3 @@ export interface InteractiveStyleRule {
  * Each rule has a selector and associated styles
  */
 export type InteractiveStyles = InteractiveStyleRule[];
-

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

@@ -1,15 +1,10 @@
 import { describe, expect, it } from 'bun:test';
-import {
-  getGroupAbbreviation,
-  getDefaultScalingType,
-  generateShortCssVar,
-  VARIABLE_TYPES,
-} from './variables';
+import { getGroupAbbreviation, getDefaultScalingType, generateShortCssVar, VARIABLE_TYPES } from './variables';
 import type { CSSVariable } from './variables';
 
 describe('VARIABLE_TYPES', () => {
   it('has all expected scaling types', () => {
-    const values = VARIABLE_TYPES.map(t => t.value);
+    const values = VARIABLE_TYPES.map((t) => t.value);
     expect(values).toEqual(['fontSize', 'padding', 'margin', 'gap', 'borderRadius', 'size', 'none']);
   });
 });
@@ -97,9 +92,7 @@ describe('generateShortCssVar', () => {
   });
 
   it('extends prefix on collision', () => {
-    const existing: CSSVariable[] = [
-      { name: 'H', cssVar: '--h-ls', value: '1px', type: 'none' },
-    ];
+    const existing: CSSVariable[] = [{ name: 'H', cssVar: '--h-ls', value: '1px', type: 'none' }];
     const result = generateShortCssVar('Heading', 'letter-spacing', existing);
     expect(result).toBe('--he-ls');
   });
@@ -130,9 +123,7 @@ describe('generateShortCssVar', () => {
   });
 
   it('adds numeric suffix for no-group collisions', () => {
-    const existing: CSSVariable[] = [
-      { name: '', cssVar: '--my-var', value: '1px', type: 'none' },
-    ];
+    const existing: CSSVariable[] = [{ name: '', cssVar: '--my-var', value: '1px', type: 'none' }];
     const result = generateShortCssVar('My Var', '', existing);
     expect(result).toBe('--my-var-2');
   });