meno-core 1.0.53 → 1.1.0

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 */
@@ -62,14 +62,37 @@ export interface CMSSchema {
   id: string;
   /** Display name for the collection */
   name: string;
-  /** Which field to use for URL slug */
-  slugField: string;
-  /** URL pattern, e.g., "/blog/{{slug}}" */
-  urlPattern: string;
+  /**
+   * Backing store for the collection's items. `'cms'` (default/omitted) = file-backed items
+   * under `cms/<id>/` (editable in Meno). `'sanity'` = read-only items fetched from a public
+   * Sanity dataset at build/SSR (authored in Sanity Studio, never written by Meno); the template
+   * page's `getStaticPaths` calls `getSanityData(documentType)` instead of `getCollection`.
+   */
+  source?: 'cms' | 'sanity';
+  /** Sanity document `_type` to fetch (only when `source === 'sanity'`). */
+  documentType?: string;
+  /**
+   * Which field to use for the URL slug. Omitted for a **data-only collection** — one
+   * with no per-item route (structured data bound to lists/cards, e.g. Team, Testimonials,
+   * Settings). When present, the collection has a template route.
+   */
+  slugField?: string;
+  /**
+   * URL pattern, e.g. `"/blog/{{slug}}"`. Omitted for a **data-only collection** (no
+   * per-item route is emitted). Its absence is what marks a collection as data-only.
+   */
+  urlPattern?: string;
   /** Field definitions */
   fields: Record<string, CMSFieldDefinition>;
   /** Client-side data configuration for dynamic filtering */
   clientData?: CMSClientDataConfig;
+  /**
+   * Generate an RSS 2.0 feed for this collection at `<route-prefix>/rss.xml`
+   * (e.g. a `/blog/{{slug}}` collection → `/blog/rss.xml`). Item title/description/date
+   * are auto-detected from the schema fields by convention; the item link uses its
+   * synthesized `_url`. Only meaningful for a routed collection (one with a `urlPattern`).
+   */
+  rss?: boolean;
 }
 
 /**
@@ -156,7 +179,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 +188,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 */
@@ -286,33 +309,66 @@ const IRREGULAR_PLURALS: Record<string, string> = {
 };
 
 /**
- * Convert a collection name to its singular form for use as item variable name.
- * Used when itemAs is not explicitly specified.
- *
- * @example
- * singularize('posts') // 'post'
- * singularize('categories') // 'category'
- * singularize('author') // 'author'
+ * Coerce a name into a valid JS identifier for use as a `.map` loop variable / forwarded
+ * prop name. Collection names allow `-`, `.` and spaces (e.g. "case-study"), none of which
+ * are legal in an identifier — emitted raw they produce `list.map((case-study) => …)`, a
+ * SyntaxError. Kebab/space/dot separators camelCase together; a leading digit is prefixed.
+ * Already-valid names pass through unchanged (no behavior change for typical collections).
  */
-export function singularize(collection: string): string {
+function toIdentifier(name: string): string {
+  if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)) return name;
+  const parts = name.split(/[^A-Za-z0-9]+/).filter(Boolean);
+  if (parts.length === 0) return 'item';
+  const camel =
+    parts[0] +
+    parts
+      .slice(1)
+      .map((p) => p[0]!.toUpperCase() + p.slice(1))
+      .join('');
+  return /^[0-9]/.test(camel) ? `_${camel}` : camel;
+}
+
+/** Apply English plural→singular rules (caller-facing identifier sanitization happens in {@link singularize}). */
+function singularizeRaw(collection: string): string {
   // Check irregular plurals first
   if (IRREGULAR_PLURALS[collection]) {
     return IRREGULAR_PLURALS[collection];
   }
   // Handle -ies -> -y (e.g., "stories" -> "story")
   if (collection.endsWith('ies')) {
-    return collection.slice(0, -3) + 'y';
+    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
   return collection.endsWith('s') ? collection.slice(0, -1) : collection;
 }
 
+/**
+ * Convert a collection name to its singular form for use as item variable name.
+ * Used when itemAs is not explicitly specified. The result is always a valid JS
+ * identifier (the value is emitted as a `.map` loop variable), and a non-string/empty
+ * input degrades to the generic `'item'` rather than throwing.
+ *
+ * @example
+ * singularize('posts') // 'post'
+ * singularize('categories') // 'category'
+ * singularize('author') // 'author'
+ * singularize('case-study') // 'caseStudy' (sanitized to a valid identifier)
+ */
+export function singularize(collection: string): string {
+  if (typeof collection !== 'string' || collection === '') return 'item';
+  return toIdentifier(singularizeRaw(collection));
+}
+
 /**
  * Describes a location where a CMS item is referenced.
  * Used for delete warnings and reference tracking.

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
@@ -134,6 +134,14 @@ export interface StructuredComponentDefinition {
   libraries?: LibrariesConfig;
   /** Whether instances of this component can have styles applied to the wrapper */
   acceptsStyles?: boolean;
+  /**
+   * Verbatim frontmatter passthrough — hand-authored `.astro` frontmatter statements the
+   * codec can't model (foreign `import`s, helper `const`/`function`s, `import.meta.env`
+   * access, etc.). Captured byte-for-byte on parse and re-emitted unchanged so a component
+   * carrying arbitrary frontmatter round-trips. Emit-side it is appended after the
+   * generated frontmatter consts. See the dialect spec §10 (escape hatches).
+   */
+  _frontmatter?: string;
 }
 
 /**
@@ -141,9 +149,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;
 }
 
@@ -163,20 +171,38 @@ export interface JSONPage {
   components?: Record<string, ComponentDefinition>;
   root?: ComponentNode;
   _lineMap?: Record<string, LineRange>;
+  /**
+   * Verbatim frontmatter passthrough — hand-authored `.astro` frontmatter statements the
+   * codec can't model (foreign `import`s, top-level `const`/`function`s, `getStaticPaths`
+   * helpers, `import.meta.env` access, etc.). Captured byte-for-byte on parse and re-emitted
+   * unchanged so a page carrying arbitrary frontmatter round-trips instead of being flagged
+   * read-only. Emit-side it is appended after the generated `const meta`/frontmatter consts.
+   * See the dialect spec §10 (escape hatches).
+   */
+  _frontmatter?: string;
+  /**
+   * Set when the source file renders under Astro but is outside the meno-astro dialect
+   * (can't be modeled into a node tree) — e.g. a hand-authored SSR page with arbitrary
+   * frontmatter. The editor shows a read-only info state instead of a (lossy) tree, and the
+   * Astro page provider's save() no-ops to protect the hand-authored source from clobber.
+   */
+  _unsupported?: { reason: string };
 }
 
 /**
  * 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 } 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.
  */
@@ -60,6 +60,9 @@ export type {
   RouteHandler,
   PageMetaData,
   PageCmsConfig,
+  PageDataConfig,
+  PageDataSource,
+  DataFieldType,
   CustomCodeConfig,
 } from './api';
 
@@ -178,6 +181,7 @@ export type {
   CommentStatus,
   CommentAuthor,
   CommentNodeIdentity,
+  CommentNodeRefSegment,
   CommentAnchor,
   CommentThreadEntry,
   Comment,
@@ -185,5 +189,24 @@ export type {
 
 export { COMMENT_STATUSES } from './comment';
 
-// Note: Path types are exported from ../paths/index.ts, not from here
+// Permission types
+export type {
+  PermissionRole,
+  ResourceKind,
+  ConfigArea,
+  ResourceRef,
+  PermissionRule,
+  PermissionGrant,
+  PermissionsPolicy,
+  PermissionIdentity,
+  ResolvedPermissions,
+} from './permissions';
 
+export {
+  PERMISSION_ROLES,
+  RESOURCE_KINDS,
+  CONFIG_AREAS,
+  CURRENT_PERMISSIONS_VERSION,
+} from './permissions';
+
+// Note: Path types are exported from ../paths/index.ts, not from here