meno-core 1.0.53 → 1.1.0

package/lib/shared/utilityClassNames.test.ts

@@ -0,0 +1,38 @@
+import { describe, test, expect } from 'bun:test';
+import { encodeArbitraryValue, decodeArbitraryValue } from './utilityClassNames';
+
+describe('encodeArbitraryValue / decodeArbitraryValue', () => {
+  describe('reversible (decode ∘ encode === identity)', () => {
+    const cases: Array<[string, string]> = [
+      ['single token', '24px'],
+      ['spaces → underscores', '92px 0'],
+      ['multi-token shorthand', '1px solid red'],
+      ['literal underscore escaped', 'slide_in'],
+      ['underscore + spaces', 'fade_in 2s ease'],
+      ['underscore inside url() preserved', 'url(a_b.png)'],
+      ['calc with spaces', 'calc(100% - 24px)'],
+    ];
+    for (const [name, value] of cases) {
+      test(name, () => {
+        const encoded = encodeArbitraryValue(value);
+        expect(encoded).not.toBeNull();
+        // no raw spaces / quotes leak into the class token
+        expect(encoded!).not.toMatch(/[\s"']/);
+        expect(decodeArbitraryValue(encoded!)).toBe(value);
+      });
+    }
+
+    test('literal underscore encodes via the \\_ escape', () => {
+      expect(encodeArbitraryValue('slide_in')).toBe('slide\\_in');
+      expect(encodeArbitraryValue('fade_in 2s ease')).toBe('fade\\_in_2s_ease');
+    });
+  });
+
+  describe('un-encodable → null (defer to side-channel)', () => {
+    for (const value of ['"a a"', "'x'", '[grid]', 'a\\b', 'url("a b.png")']) {
+      test(JSON.stringify(value), () => {
+        expect(encodeArbitraryValue(value)).toBeNull();
+      });
+    }
+  });
+});

package/lib/shared/utilityClassNames.ts

@@ -0,0 +1,458 @@
+/**
+ * Tailwind-style utility class name parsing & value encoding.
+ *
+ * Shared by the forward mapper (utilityClassMapper.ts) and the CSS generator
+ * (cssGeneration.ts) so class names encode and decode identically everywhere.
+ *
+ * Class name grammar (after stripping an optional `breakpoint:` variant):
+ *   - static utilities:      `flex`, `hidden`, `justify-center`, `uppercase`, …
+ *   - presets:               `shadow-2`, `bg-gradient-1`, `border-preset-0`
+ *   - arbitrary values:      `p-[40px]`, `w-[50%]`, `m-[92px_0]` (spaces → `_`)
+ *   - CSS variables:         `bg-(--primary)`, `text-(length:--font-size-lg)`
+ *   - named keywords:        `w-full`, `h-screen`, `m-auto`, `rounded-full`
+ *   - bare numbers:          `z-10`, `order-2`, `opacity-50` (= 0.5)
+ *   - arbitrary properties:  `[clip-path:circle(50%)]`, `[background:…]`
+ *   - hash fallback:         `pt-h1y9pr6i` (value lives in the style-value registry)
+ */
+
+import {
+  prefixToCSSProperty,
+  staticUtilityReverse,
+  presetClassReverse,
+  keywordValues,
+  genericKeywordRoots,
+  integerValueRoots,
+  propertyOrder,
+  SPACING_SCALE,
+  SPACING_SCALE_ROOTS,
+  COLOR_TOKEN_ROOTS,
+} from './utilityClassConfig';
+import { isCssNamedColor } from './cssNamedColors';
+
+/** Class roots sorted longest-first so `border-t-…` wins over `border-…`. */
+export const SORTED_ROOTS: readonly string[] = Object.keys(prefixToCSSProperty).sort((a, b) => b.length - a.length);
+
+/** Convert a camelCase style property to its kebab-case CSS name. */
+export function camelToKebab(prop: string): string {
+  return prop.replace(/([A-Z])/g, '-$1').toLowerCase();
+}
+
+// kebab-case CSS property → camelCase style property, for all known properties.
+const kebabToCamelMap: Record<string, string> = (() => {
+  const map: Record<string, string> = {};
+  for (const prop of propertyOrder) {
+    map[camelToKebab(prop)] = prop;
+  }
+  return map;
+})();
+
+/** Convert a kebab-case CSS property back to its camelCase style property. */
+export function cssPropertyToCamel(property: string): string {
+  return kebabToCamelMap[property] ?? property.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+/**
+ * Roots that decode to a different camelCase property than their kebab CSS
+ * property suggests (px → paddingInline, not padding).
+ */
+export const ROOT_CAMEL_OVERRIDES: Record<string, string> = {
+  px: 'paddingInline',
+  py: 'paddingBlock',
+  mx: 'marginInline',
+  my: 'marginBlock',
+};
+
+// ---------------------------------------------------------------------------
+// Arbitrary value encoding (Tailwind bracket convention: spaces → underscores)
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply `transform` to every part of `input` that is NOT inside a `url(...)`
+ * segment. Tailwind preserves underscores inside url() — so do we, in both
+ * encode and decode directions.
+ */
+function transformOutsideUrl(input: string, transform: (segment: string) => string): string {
+  let result = '';
+  let i = 0;
+  const lower = input.toLowerCase();
+  while (i < input.length) {
+    const idx = lower.indexOf('url(', i);
+    if (idx === -1) {
+      result += transform(input.slice(i));
+      break;
+    }
+    result += transform(input.slice(i, idx));
+    // Copy the url(...) segment verbatim up to its matching close paren
+    let depth = 0;
+    let j = idx + 3; // position of '('
+    for (; j < input.length; j++) {
+      if (input[j] === '(') depth++;
+      else if (input[j] === ')') {
+        depth--;
+        if (depth === 0) {
+          j++;
+          break;
+        }
+      }
+    }
+    result += input.slice(idx, j);
+    i = j;
+  }
+  return result;
+}
+
+/**
+ * Encode a CSS value for a Tailwind arbitrary-value class: spaces become
+ * underscores (`92px 0` → `92px_0`), and literal underscores are escaped as
+ * `\_` (`slide_in 2s` → `slide\_in_2s`) so they survive the decode — the `\_`
+ * escape is CSS-selector-safe (`escapeCSSClassName` turns the `\` into `\\`).
+ *
+ * Returns null when the value still can't be encoded reversibly — quotes,
+ * brackets, stray backslashes, or whitespace/quotes inside url(). Those callers
+ * fall back to a hash class + style-value registry entry (ephemeral; for the
+ * class-string-as-source migration they must move to a structured remainder —
+ * see docs/meno-class-styling-migration.md §5).
+ */
+export function encodeArbitraryValue(value: string): string | null {
+  let ok = true;
+  const encoded = transformOutsideUrl(value, (segment) => {
+    // Quotes/brackets/backslash can't live safely in a class attribute or the
+    // `[..]` value — reject (→ side-channel). Underscores ARE representable via
+    // the `\_` escape, so they're allowed.
+    if (/["'\\[\]]/.test(segment)) ok = false;
+    // Escape literal underscores BEFORE collapsing whitespace, so the
+    // underscores we introduce for spaces aren't themselves escaped.
+    return segment.replace(/_/g, '\\_').replace(/\s+/g, '_');
+  });
+  if (!ok) return null;
+  // Strip our own `\_` escapes, then reject anything still problematic — those
+  // chars can only have survived verbatim from inside a url(...) segment.
+  const guardTarget = encoded.replace(/^\[|\]$/g, '').replace(/\\_/g, '');
+  if (/[\s"'\\[\]]/.test(guardTarget)) return null;
+  return encoded;
+}
+
+/**
+ * Decode a Tailwind arbitrary value: `\_` → literal underscore and bare `_` →
+ * space, in a single pass (so an escaped underscore isn't first read as a
+ * space). Content inside url(...) is left verbatim.
+ */
+export function decodeArbitraryValue(encoded: string): string {
+  return transformOutsideUrl(encoded, (segment) => segment.replace(/\\_|_/g, (m) => (m === '\\_' ? '_' : ' ')));
+}
+
+// ---------------------------------------------------------------------------
+// Value-type classification (for roots shared by several properties)
+// ---------------------------------------------------------------------------
+
+const FONT_SIZE_KEYWORDS = new Set([
+  'xx-small',
+  'x-small',
+  'small',
+  'medium',
+  'large',
+  'x-large',
+  'xx-large',
+  'xxx-large',
+  'larger',
+  'smaller',
+]);
+
+/** True when a value reads as a color (hex, color function, named color, var()). */
+export function isColorValue(value: string): boolean {
+  if (value.startsWith('#') || value.startsWith('var(')) return true;
+  if (/^(rgb|rgba|hsl|hsla|oklch|oklab|lab|lch|hwb|color|color-mix)\(/i.test(value)) return true;
+  if (value === 'transparent' || value === 'currentColor' || value === 'currentcolor') return true;
+  return isCssNamedColor(value);
+}
+
+/**
+ * True for a bare Meno color token (e.g. `primary`, `background-light`) that
+ * resolves to `var(--token)`. Rejects: named CSS colors / hex / color functions
+ * / `transparent` / `currentColor` (those are real colors, not tokens), and the
+ * Tailwind palette shape `word-<number>` (`gray-500`, `blue-600`) so foreign
+ * Tailwind classes carried verbatim in `class=""` aren't misread as Meno tokens.
+ *
+ * Shared by the forward mapper (token → `bg-primary`) and inverse parser
+ * (`bg-primary` → `var(--primary)`) so the two stay symmetric.
+ */
+export function isBareColorTokenName(value: string): boolean {
+  if (!/^[a-zA-Z][\w-]*$/.test(value)) return false;
+  if (isColorValue(value)) return false;
+  if (/^[a-z]+-\d/i.test(value)) return false;
+  return true;
+}
+
+/** True when a `text-…` value reads as a font-size (length/number/keyword). */
+function isFontSizeValue(value: string): boolean {
+  if (/^[\d.+-]/.test(value)) return true;
+  if (/^(calc|clamp|min|max)\(/i.test(value)) return true;
+  return FONT_SIZE_KEYWORDS.has(value);
+}
+
+/** True when a `font-…` value reads as a font-weight (numeric). */
+function isFontWeightValue(value: string): boolean {
+  return /^\d+(\.\d+)?$/.test(value);
+}
+
+/** True when a `bg-…` value reads as a background-image (url()/gradients). */
+function isImageValue(value: string): boolean {
+  return /^(url|linear-gradient|radial-gradient|conic-gradient|repeating-linear-gradient|repeating-radial-gradient|repeating-conic-gradient|image-set|cross-fade|element)\(/i.test(
+    value,
+  );
+}
+
+/** True for a single length token like `2px`, `0.5rem`, `-4px`. */
+function isLengthValue(value: string): boolean {
+  return /^-?[\d.]+[a-z%]*$/i.test(value);
+}
+
+/**
+ * True when the value contains whitespace OUTSIDE any parentheses, i.e. it's a
+ * multi-token shorthand (`1px solid red`) rather than a single token. A color
+ * function like `rgba(0, 0, 0, 0)` or `color-mix(in srgb, …)` carries internal
+ * spaces but is still ONE token — those must not read as a shorthand, otherwise
+ * a transparent `border-color` collapses into the `border` shorthand and stops
+ * overriding the width/style declaration independently.
+ */
+function hasTopLevelWhitespace(value: string): boolean {
+  let depth = 0;
+  for (let i = 0; i < value.length; i++) {
+    const ch = value[i] ?? '';
+    if (ch === '(') depth++;
+    else if (ch === ')') depth = Math.max(0, depth - 1);
+    else if (depth === 0 && /\s/.test(ch)) return true;
+  }
+  return false;
+}
+
+/**
+ * Resolve the CSS property for a class root, disambiguating Tailwind's shared
+ * roots by value type (`text-[14px]` → font-size, `text-[#fff]` → color, …).
+ */
+export function resolveRootProperty(root: string, value: string): string {
+  switch (root) {
+    case 'text':
+      return isFontSizeValue(value) ? 'font-size' : 'color';
+    case 'font':
+      return isFontWeightValue(value) ? 'font-weight' : 'font-family';
+    case 'bg':
+      return isImageValue(value) ? 'background-image' : 'background-color';
+    case 'border':
+      return isColorValue(value) && !hasTopLevelWhitespace(value) ? 'border-color' : 'border';
+    case 'outline': {
+      if (hasTopLevelWhitespace(value) || value === 'none') return 'outline';
+      if (isColorValue(value)) return 'outline-color';
+      if (isLengthValue(value)) return 'outline-width';
+      return 'outline';
+    }
+    default:
+      return prefixToCSSProperty[root] ?? root;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Breakpoint variant prefix (`tablet:p-[24px]`)
+// ---------------------------------------------------------------------------
+
+/**
+ * Split an optional `breakpoint:` variant prefix off a class name.
+ * Arbitrary-property classes (`[grid-area:hero]`) never match — their colon
+ * sits inside brackets, and the prefix segment must be a bare identifier.
+ */
+export function splitVariantPrefix(className: string): { breakpoint: string | null; base: string } {
+  const match = className.match(/^([a-z][a-z0-9_-]*):(.+)$/);
+  if (match) {
+    return { breakpoint: match[1] ?? null, base: match[2] ?? className };
+  }
+  return { breakpoint: null, base: className };
+}
+
+/**
+ * Tailwind's desktop-first (max-width) variant marker. Meno breakpoints cascade desktop→mobile
+ * (`base` = widest, narrower breakpoints override via `max-width`), which is exactly Tailwind's
+ * `max-*` variant direction — so the class form is `max-<name>:` (`max-lg:p-4`), reading
+ * unambiguously as "this width and narrower". A bare prefix would read as Tailwind's mobile-first
+ * MIN-width (the opposite cascade), so the explicit `max-` keeps the class legible.
+ */
+export const DESKTOP_FIRST_VARIANT_PREFIX = 'max-';
+
+/**
+ * Class-name aliases for Meno's two default breakpoints. The breakpoint IDENTITY stays `tablet`/
+ * `mobile` everywhere (style model, UI labels, responsive-scales config) — only the emitted/parsed
+ * CLASS STRING uses Tailwind's canonical scale names: `tablet` (max-width 1024px) ⇄ `lg` (Tailwind's
+ * lg = 1024px, an exact match), `mobile` (max-width 540px) ⇄ `sm`. NB Meno keeps its 540px mobile
+ * threshold even though Tailwind's `sm` is 640px. Custom breakpoints have no alias (use their own
+ * name). Codec-only — nothing else in the system is renamed.
+ */
+const BREAKPOINT_NAME_TO_CLASS: Record<string, string> = { tablet: 'lg', mobile: 'sm' };
+const CLASS_NAME_TO_BREAKPOINT: Record<string, string> = { lg: 'tablet', sm: 'mobile' };
+
+/** Build the class variant prefix for a breakpoint name: `tablet` → `max-lg:`, `mobile` → `max-sm:`. */
+export function breakpointClassPrefix(breakpointName: string): string {
+  const lower = breakpointName.toLowerCase();
+  const aliased = BREAKPOINT_NAME_TO_CLASS[lower] ?? lower;
+  return `${DESKTOP_FIRST_VARIANT_PREFIX}${aliased}:`;
+}
+
+/**
+ * All class prefixes that resolve to a breakpoint, for READ-side recognition (write paths emit only
+ * the canonical `breakpointClassPrefix`). For `tablet` this is the canonical `max-lg:`, the
+ * un-aliased `max-tablet:` (emitted briefly before the alias landed), and the legacy bare `tablet:`
+ * (pre-`max-` projects). Deliberately NOT the bare `lg:`/`sm:` — Meno never emitted those, and a bare
+ * `lg:` is a foreign real-Tailwind (min-width) token we must not absorb.
+ */
+export function breakpointClassPrefixes(breakpointName: string): string[] {
+  const lower = breakpointName.toLowerCase();
+  const aliased = BREAKPOINT_NAME_TO_CLASS[lower];
+  const prefixes = [`${DESKTOP_FIRST_VARIANT_PREFIX}${lower}:`, `${lower}:`]; // max-tablet:, tablet:
+  if (aliased) prefixes.unshift(`${DESKTOP_FIRST_VARIANT_PREFIX}${aliased}:`); // max-lg: (canonical, first)
+  return prefixes;
+}
+
+/**
+ * Normalize a parsed variant segment (from {@link splitVariantPrefix}) to the INTERNAL breakpoint
+ * name. The alias only applies behind the `max-` marker (a definite Meno desktop-first class):
+ * `max-lg`/`max-sm` → `tablet`/`mobile`, `max-tablet` → `tablet`, `max-<custom>` → `<custom>`. Bare
+ * segments pass through untouched — legacy Meno `tablet`/`mobile` map to themselves, and a foreign
+ * bare `lg`/`hover` is left alone (so it stays a non-modeled / foreign token, never mis-absorbed).
+ */
+export function normalizeBreakpointVariant(variant: string | null): string | null {
+  if (variant?.startsWith(DESKTOP_FIRST_VARIANT_PREFIX)) {
+    const bare = variant.slice(DESKTOP_FIRST_VARIANT_PREFIX.length);
+    return CLASS_NAME_TO_BREAKPOINT[bare] ?? bare;
+  }
+  return variant;
+}
+
+// ---------------------------------------------------------------------------
+// Class name parsing
+// ---------------------------------------------------------------------------
+
+export interface ParsedUtilityClass {
+  /** kebab-case CSS property the class targets */
+  property: string;
+  /** Decoded CSS value; null for hash classes (resolve via style-value registry) */
+  value: string | null;
+  /** The class root (`p`, `text`, `bg`, …); null for statics/presets/arbitrary properties */
+  root: string | null;
+  kind: 'static' | 'preset' | 'arbitrary' | 'var' | 'keyword' | 'numeric' | 'hash' | 'arbitrary-property';
+}
+
+const HASH_VALUE_RE = /^h[0-9a-z]+$/;
+
+/**
+ * Parse a single (unprefixed) utility class name into its CSS property and
+ * decoded value. Returns null for class names that aren't Meno utilities.
+ *
+ * `knownTokens` is the project's defined design-token names (color + variable
+ * names). It gates the bare color-token form (`bg-primary` → `var(--primary)`):
+ * `bg-<name>` is only read as a token when `<name>` is in this set. Without it,
+ * `bg-<word>` stays UNRECOGNIZED — so foreign / authored classes (`text-wrapper`,
+ * imported `bg-dark`) are never misclassified. The `var(--…)` shorthand form
+ * (`bg-(--primary)`) is self-describing and needs no token set.
+ */
+export function parseUtilityClass(className: string, knownTokens?: ReadonlySet<string>): ParsedUtilityClass | null {
+  const stat = staticUtilityReverse[className];
+  if (stat) {
+    return { property: camelToKebab(stat.prop), value: stat.value, root: null, kind: 'static' };
+  }
+
+  const preset = presetClassReverse[className];
+  if (preset) {
+    return { property: camelToKebab(preset.prop), value: preset.value, root: null, kind: 'preset' };
+  }
+
+  // Arbitrary property: [clip-path:circle(50%)], [background:linear-gradient(…)]
+  const arbProp = className.match(/^\[([a-z-]+):(.+)\]$/);
+  if (arbProp) {
+    return {
+      property: arbProp[1] ?? '',
+      value: decodeArbitraryValue(arbProp[2] ?? ''),
+      root: null,
+      kind: 'arbitrary-property',
+    };
+  }
+
+  for (const root of SORTED_ROOTS) {
+    if (!className.startsWith(`${root}-`)) continue;
+    const rest = className.slice(root.length + 1);
+    if (!rest) continue;
+    const parsed = parseRootValue(root, rest, knownTokens);
+    if (parsed) return parsed;
+  }
+
+  return null;
+}
+
+function parseRootValue(root: string, rest: string, knownTokens?: ReadonlySet<string>): ParsedUtilityClass | null {
+  // Arbitrary value: root-[value]
+  if (rest.startsWith('[') && rest.endsWith(']') && rest.length > 2) {
+    const value = decodeArbitraryValue(rest.slice(1, -1));
+    return { property: resolveRootProperty(root, value), value, root, kind: 'arbitrary' };
+  }
+
+  // CSS variable: root-(--name) / root-(length:--name)
+  const varMatch = rest.match(/^\((?:([a-z-]+):)?(--[\w-]+)\)$/);
+  if (varMatch) {
+    const hint = varMatch[1];
+    const value = `var(${varMatch[2]})`;
+    let property: string;
+    if (root === 'text') {
+      property = hint === 'length' ? 'font-size' : 'color';
+    } else if (root === 'font') {
+      // `font-*` is shared by font-weight and font-family; a var value is ambiguous, so the
+      // emitter tags weight vars with a `number:` hint (see utilityClassMapper). Default to
+      // font-family (the original behavior for an un-hinted var like `font-(--l-ff)`).
+      property = hint === 'number' ? 'font-weight' : 'font-family';
+    } else {
+      property = resolveRootProperty(root, value);
+    }
+    return { property, value, root, kind: 'var' };
+  }
+
+  // Named keyword: w-full, m-auto, rounded-full
+  const keyword = keywordValues[root]?.[rest];
+  if (keyword !== undefined) {
+    return { property: resolveRootProperty(root, keyword), value: keyword, root, kind: 'keyword' };
+  }
+
+  // Generic keyword roots: cursor-pointer, align-middle, origin-center, …
+  if (genericKeywordRoots.has(root) && /^[a-z][a-z-]*$/.test(rest)) {
+    return { property: resolveRootProperty(root, rest), value: rest, root, kind: 'keyword' };
+  }
+
+  // Named spacing scale: p-4 → 16px, gap-6 → 24px (Tailwind's step table).
+  if (SPACING_SCALE_ROOTS.has(root)) {
+    const scaleVal = SPACING_SCALE[rest];
+    if (scaleVal !== undefined) {
+      return { property: resolveRootProperty(root, scaleVal), value: scaleVal, root, kind: 'keyword' };
+    }
+  }
+
+  // Bare numbers: z-10, order-2, flex-2; opacity uses Tailwind's 0–100 scale
+  if (integerValueRoots.has(root) && /^-?\d+$/.test(rest)) {
+    return { property: prefixToCSSProperty[root] ?? root, value: rest, root, kind: 'numeric' };
+  }
+  if (root === 'opacity' && /^\d{1,3}$/.test(rest)) {
+    return { property: 'opacity', value: String(Number(rest) / 100), root, kind: 'numeric' };
+  }
+
+  // Bare design-token color (Meno convention): bg-primary → var(--primary),
+  // text-text → var(--text), border-border → var(--border). Gated on the
+  // project's `knownTokens` so `bg-<word>` is read as a token ONLY for a DEFINED
+  // token name — foreign / authored classes (`text-wrapper`, imported `bg-dark`)
+  // are left unrecognized. The token gate also resolves the `h…`-token vs
+  // hash-class ambiguity (a real hash class's `rest` is never a defined token).
+  if (COLOR_TOKEN_ROOTS.has(root) && knownTokens?.has(rest)) {
+    const value = `var(--${rest})`;
+    return { property: resolveRootProperty(root, value), value, root, kind: 'var' };
+  }
+
+  // Hash fallback: value lives in the style-value registry
+  if (HASH_VALUE_RE.test(rest)) {
+    return { property: prefixToCSSProperty[root] ?? root, value: null, root, kind: 'hash' };
+  }
+
+  return null;
+}

package/lib/shared/utils.test.ts

@@ -244,18 +244,10 @@ describe('utils', () => {
 
     test('should handle complex children array', () => {
       const node = {
-        children: [
-          { element: 'div' },
-          { element: 'span' },
-          'text',
-        ],
+        children: [{ element: 'div' }, { element: 'span' }, 'text'],
       };
       normalizeChildrenArray(node);
-      expect(node.children).toEqual([
-        { element: 'div' },
-        { element: 'span' },
-        'text',
-      ]);
+      expect(node.children).toEqual([{ element: 'div' }, { element: 'span' }, 'text']);
     });
   });
 });

package/lib/shared/utils.ts

@@ -20,7 +20,7 @@ export function deepClone<T>(obj: T): T {
  * @param ms - Milliseconds to wait
  */
 export function wait(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms));
+  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
 /**
@@ -50,7 +50,20 @@ export function isEditableElement(): boolean {
   // For inputs, only block shortcuts for text-accepting types
   if (activeElement.tagName === 'INPUT') {
     const inputType = (activeElement as HTMLInputElement).type.toLowerCase();
-    const textInputTypes = ['text', 'password', 'email', 'number', 'search', 'tel', 'url', 'date', 'time', 'datetime-local', 'month', 'week'];
+    const textInputTypes = [
+      'text',
+      'password',
+      'email',
+      'number',
+      'search',
+      'tel',
+      'url',
+      'date',
+      'time',
+      'datetime-local',
+      'month',
+      'week',
+    ];
     // Allow shortcuts for: checkbox, radio, button, submit, reset, color, file, range, hidden
     return textInputTypes.includes(inputType);
   }
@@ -59,10 +72,7 @@ export function isEditableElement(): boolean {
   // This handles rich text editors where focus may be on an internal element
   let element: Element | null = activeElement;
   while (element) {
-    if (
-      element.hasAttribute('contenteditable') ||
-      (element as HTMLElement).isContentEditable
-    ) {
+    if (element.hasAttribute('contenteditable') || (element as HTMLElement).isContentEditable) {
       return true;
     }
     element = element.parentElement;
@@ -75,7 +85,7 @@ export function isEditableElement(): boolean {
  * Extract the parent path from a tree path
  * Example: root_0_children_0 -> root_0, root_0_children_0_children_1 -> root_0_children_0
  * Also accepts array paths: [0,0] -> "root_0", [0,0,1] -> "root_0_children_0"
- * 
+ *
  * @param treePath - The tree path (string or Path array)
  * @param rootPath - The root path constant (default: 'root_0')
  * @returns The parent path, or rootPath if no parent found
@@ -83,12 +93,12 @@ export function isEditableElement(): boolean {
 export function getParentPathFromTreePath(treePath: string | Path, rootPath: string = ROOT_0_STRING): string {
   // Convert to array if needed
   const pathArray = typeof treePath === 'string' ? stringToPath(treePath) : treePath;
-  
+
   // Handle root paths
   if (isRootPathArray(pathArray)) {
     return rootPath;
   }
-  
+
   // Use array operations to get parent path
   const parentArray = getParentPath(pathArray);
   return pathToLegacyString(parentArray);
@@ -109,4 +119,3 @@ export function normalizeChildrenArray(node: { children?: any[] | any }): void {
   }
   // If already an array, no change needed
 }
-

package/lib/shared/validation/cmsValidators.ts

@@ -14,7 +14,8 @@ export const CMS_COLLECTION_ID_REGEX = /^[a-zA-Z0-9_-]+$/;
 /**
  * Zod schema for CMS collection ID validation
  */
-export const CMSCollectionIdSchema = z.string()
+export const CMSCollectionIdSchema = z
+  .string()
   .min(1, 'Collection ID is required')
   .regex(CMS_COLLECTION_ID_REGEX, 'Collection ID must contain only letters, numbers, underscores, and hyphens');
 

package/lib/shared/validation/commentValidators.test.ts

@@ -0,0 +1,53 @@
+import { describe, test, expect } from 'bun:test';
+import { validateComment } from './commentValidators';
+
+/** A minimal valid comment; callers override `anchor` to exercise schema variants. */
+function baseComment(anchor: Record<string, unknown>): Record<string, unknown> {
+  return {
+    _id: 'c1',
+    _filename: 'c1.json',
+    _pagePath: 'index',
+    _seq: 1,
+    _createdAt: '2026-01-01T00:00:00.000Z',
+    _updatedAt: '2026-01-01T00:00:00.000Z',
+    _commitSha: null,
+    anchor,
+    status: 'open',
+    thread: [
+      {
+        id: 't1',
+        author: { login: 'local' },
+        createdAt: '2026-01-01T00:00:00.000Z',
+        text: 'hi',
+        statusChange: null,
+      },
+    ],
+  };
+}
+
+const pageLevelAnchor = {
+  nodePath: [0, 1],
+  nodeIdentity: { kind: 'node', name: 'div' },
+  offsetXPercent: 0.5,
+  offsetYPercent: 0.5,
+};
+
+describe('validateComment — element anchor identity', () => {
+  test('accepts a comment WITHOUT a cmsItemIndexPath (element not in a list)', () => {
+    const result = validateComment(baseComment(pageLevelAnchor));
+    expect(result.valid).toBe(true);
+    if (result.valid) expect(result.data.anchor.cmsItemIndexPath).toBeUndefined();
+  });
+
+  test('accepts and round-trips a comment WITH a cmsItemIndexPath', () => {
+    const cmsItemIndexPath = [0, 2];
+    const result = validateComment(baseComment({ ...pageLevelAnchor, cmsItemIndexPath }));
+    expect(result.valid).toBe(true);
+    if (result.valid) expect(result.data.anchor.cmsItemIndexPath).toEqual(cmsItemIndexPath);
+  });
+
+  test('rejects a malformed cmsItemIndexPath (non-number entries)', () => {
+    const result = validateComment(baseComment({ ...pageLevelAnchor, cmsItemIndexPath: ['a', 'b'] }));
+    expect(result.valid).toBe(false);
+  });
+});

package/lib/shared/validation/commentValidators.ts

@@ -23,8 +23,19 @@ export const CommentNodeIdentitySchema = z.object({
   label: z.string().optional(),
 });
 
+export const CommentNodeRefSegmentSchema = z.object({
+  kind: z.enum(['component', 'node']),
+  name: z.string().min(1),
+  nth: z.number().int().nonnegative(),
+});
+
 export const CommentAnchorSchema = z.object({
+  // Type + occurrence path (move-resilient source of truth). Must be declared
+  // (z.object strips unknown keys) so it round-trips to disk.
+  nodeRef: z.array(CommentNodeRefSegmentSchema).optional(),
   nodePath: z.array(z.number().int().nonnegative()),
+  // CMS-list item path disambiguating which list copy the element belongs to.
+  cmsItemIndexPath: z.array(z.number().int().nonnegative()).optional(),
   nodeIdentity: CommentNodeIdentitySchema,
   offsetXPercent: z.number().min(0).max(1),
   offsetYPercent: z.number().min(0).max(1),
@@ -53,7 +64,7 @@ export const CommentSchema = z.object({
 });
 
 function zodToValidationErrors(zodError: ZodError): ValidationError[] {
-  return zodError.errors.map(err => ({
+  return zodError.errors.map((err) => ({
     path: err.path.join('.') || 'root',
     message: err.message,
     code: 'INVALID_TYPE' as const,