meno-core 1.0.53 → 1.1.0

package/lib/shared/nodeUtils.ts

@@ -3,11 +3,23 @@
  * Provides helper functions for working with ComponentNode types
  */
 
-import type { ComponentNode, ComponentInstanceNode, HtmlNode, SlotMarker, EmbedNode, LinkNode, LocaleListNode, ComponentDefinition, StructuredComponentDefinition } from './types';
+import type {
+  ComponentNode,
+  ComponentInstanceNode,
+  HtmlNode,
+  SlotMarker,
+  EmbedNode,
+  LinkNode,
+  LocaleListNode,
+  ComponentDefinition,
+  StructuredComponentDefinition,
+} from './types';
 import type { ListNode } from './registry/nodeTypes/ListNodeType';
+import type { IslandNode } from './registry/nodeTypes/IslandNodeType';
+import type { CustomNode } from './registry/nodeTypes/CustomNodeType';
 
 // For backward compatibility during migration
-type CMSListNode = ListNode;
+type _CMSListNode = ListNode;
 import { NODE_TYPE } from './constants';
 
 /**
@@ -15,8 +27,20 @@ import { NODE_TYPE } from './constants';
  * These are self-closing tags like <img />, <br />, <input />, etc.
  */
 export const VOID_ELEMENTS = new Set([
-  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
-  'link', 'meta', 'param', 'source', 'track', 'wbr'
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
 ]);
 
 /**
@@ -112,13 +136,13 @@ export function extractNodeProperties(node: ComponentNode): {
   if (isComponentNode(node)) {
     return {
       componentName: node.component,
-      props: node.props || {}
+      props: node.props || {},
     };
   }
   if (isHtmlNode(node)) {
     return {
       tag: node.tag,
-      props: {}
+      props: {},
     };
   }
   return { props: {} };
@@ -129,14 +153,15 @@ export function extractNodeProperties(node: ComponentNode): {
  * This is a heuristic based on naming conventions:
  * - Components typically start with uppercase (e.g., "Card", "Button")
  * - HTML elements are lowercase (e.g., "div", "span")
- * 
+ *
  * Note: This is not foolproof, but works for most cases.
  * For accurate detection, use component registry lookup.
  */
 export function isLikelyComponentTag(tag: string): boolean {
   if (!tag) return false;
   // Components typically start with uppercase letter
-  return tag.length > 0 && tag[0] === tag[0].toUpperCase() && tag[0] !== tag[0].toLowerCase();
+  const first = tag[0];
+  return first !== undefined && first === first.toUpperCase() && first !== first.toLowerCase();
 }
 
 /**
@@ -195,6 +220,21 @@ export function isLocaleListNode(node: ComponentNode | null | undefined): node i
   return node?.type === NODE_TYPE.LOCALE_LIST;
 }
 
+/**
+ * Type guard to check if a node is an island node (BYO framework component)
+ */
+export function isIslandNode(node: ComponentNode | null | undefined): node is IslandNode {
+  return node?.type === NODE_TYPE.ISLAND;
+}
+
+/**
+ * Type guard to check if a node is a custom node (opaque hand-authored `.astro`
+ * component under `src/custom/` — Meno renders it but doesn't model its internals).
+ */
+export function isCustomNode(node: ComponentNode | null | undefined): node is CustomNode {
+  return node?.type === NODE_TYPE.CUSTOM;
+}
+
 /**
  * Type guard to check if a node is a CMS list node
  * @deprecated Use isListNode() and check sourceType === 'collection' instead.
@@ -220,17 +260,29 @@ export function isListNode(node: unknown): node is ListNode {
 /**
  * Validate that a node type is valid
  */
-export function isValidNodeType(type: string): type is typeof NODE_TYPE[keyof typeof NODE_TYPE] {
-  return type === NODE_TYPE.NODE || type === NODE_TYPE.COMPONENT || type === NODE_TYPE.SLOT ||
-    type === NODE_TYPE.EMBED || type === NODE_TYPE.LINK || type === NODE_TYPE.LOCALE_LIST ||
-    type === NODE_TYPE.LIST || type === 'cms-list'; // 'cms-list' supported for migration
+export function isValidNodeType(type: string): type is (typeof NODE_TYPE)[keyof typeof NODE_TYPE] {
+  return (
+    type === NODE_TYPE.NODE ||
+    type === NODE_TYPE.COMPONENT ||
+    type === NODE_TYPE.SLOT ||
+    type === NODE_TYPE.EMBED ||
+    type === NODE_TYPE.LINK ||
+    type === NODE_TYPE.LOCALE_LIST ||
+    type === NODE_TYPE.LIST ||
+    type === NODE_TYPE.ISLAND ||
+    type === NODE_TYPE.CUSTOM ||
+    type === NODE_TYPE.MARKDOWN ||
+    type === 'cms-list'
+  ); // 'cms-list' supported for migration
 }
 
 /**
- * Check if a node can have children property (excludes SlotMarker)
+ * Check if a node can have a children property (excludes SlotMarker and verbatim `{_code}` markers).
+ * A `_code` marker is rendered byte-for-byte by the emitter, which ignores any `children` — so
+ * letting the tree drop a node "inside" one would silently lose the dropped node on save/build.
  */
 export function canHaveChildren(node: ComponentNode | null | undefined): node is Exclude<ComponentNode, SlotMarker> {
-  return node !== null && node !== undefined && !isSlotMarker(node);
+  return node !== null && node !== undefined && !isSlotMarker(node) && (node as { _code?: unknown })._code !== true;
 }
 
 /**
@@ -258,7 +310,12 @@ export function hasIf(node: ComponentNode): node is ComponentNode & { if: IfCond
  * Check if a node is marked as slot content
  */
 export function isSlotContent(node: unknown): boolean {
-  return node != null && typeof node === 'object' && '_isSlotContent' in node && (node as Record<string, unknown>)._isSlotContent === true;
+  return (
+    node != null &&
+    typeof node === 'object' &&
+    '_isSlotContent' in node &&
+    (node as Record<string, unknown>)._isSlotContent === true
+  );
 }
 
 /**
@@ -389,10 +446,7 @@ export function isBooleanMapping(value: unknown): value is BooleanMapping {
  *   { visible: 'true' }
  * ) // true
  */
-export function evaluateNodeIf(
-  node: ComponentNode,
-  props?: Record<string, unknown>
-): boolean {
+export function evaluateNodeIf(node: ComponentNode, props?: Record<string, unknown>): boolean {
   const ifValue = hasIf(node) ? node.if : undefined;
 
   // No if property = render (default true)
@@ -441,7 +495,7 @@ export function evaluateNodeIf(
  * @returns The same node with _isSlotContent: true added to all object nodes
  */
 export function markAsSlotContent<T extends ComponentNode | ComponentNode[] | string | number | null | undefined>(
-  node: T
+  node: T,
 ): T {
   if (!node || typeof node !== 'object') return node;
 
@@ -455,8 +509,8 @@ export function markAsSlotContent<T extends ComponentNode | ComponentNode[] | st
   // Recursively mark children
   if ('children' in node && node.children) {
     if (Array.isArray(node.children)) {
-      node.children = node.children.map(child =>
-        typeof child === 'object' && child !== null ? markAsSlotContent(child) : child
+      node.children = node.children.map((child) =>
+        typeof child === 'object' && child !== null ? markAsSlotContent(child) : child,
       ) as typeof node.children;
     } else if (typeof node.children === 'object') {
       markAsSlotContent(node.children as ComponentNode);
@@ -465,4 +519,3 @@ export function markAsSlotContent<T extends ComponentNode | ComponentNode[] | st
 
   return node;
 }
-

package/lib/shared/pathArrayUtils.test.ts

@@ -5,7 +5,7 @@
 
 import { describe, it, expect } from 'bun:test';
 import {
-  Path,
+  type Path,
   ROOT_STRING,
   ROOT_0_STRING,
   CHILDREN_SEPARATOR,
@@ -312,4 +312,3 @@ describe('Path Array Utilities - Phase 1 Foundation', () => {
     });
   });
 });
-

package/lib/shared/pathArrayUtils.ts

@@ -2,7 +2,7 @@
  * Array-based path utilities
  * Paths are represented as number arrays internally: [0,0,1] instead of "root_0_children_0_children_1"
  * Root is represented as [0] (or empty array [] depending on context)
- * 
+ *
  * This file maintains backward compatibility while using the new modular path system.
  * All path utilities are re-exported from the organized path modules.
  */

package/lib/shared/pathSecurity.ts

@@ -3,7 +3,7 @@
  * Provides path traversal protection for file system operations
  */
 
-import { resolve, sep } from 'path';
+import { resolve, sep } from 'node:path';
 
 /**
  * Error thrown when a path traversal attack is detected
@@ -11,7 +11,7 @@ import { resolve, sep } from 'path';
 export class PathTraversalError extends Error {
   constructor(
     public readonly requestedPath: string,
-    public readonly rootPath: string
+    public readonly rootPath: string,
   ) {
     super(`Path traversal detected: "${requestedPath}" escapes root "${rootPath}"`);
     this.name = 'PathTraversalError';

package/lib/shared/pathUtils.test.ts

@@ -94,7 +94,9 @@ describe('pathUtils', () => {
     });
 
     test('should handle deeply nested paths', () => {
-      expect(domPathToTreePath('root_children_0_children_1_children_2')).toBe('root_0_children_0_children_1_children_2');
+      expect(domPathToTreePath('root_children_0_children_1_children_2')).toBe(
+        'root_0_children_0_children_1_children_2',
+      );
     });
   });
 
@@ -115,11 +117,7 @@ describe('pathUtils', () => {
     });
 
     test('should handle deeply nested paths', () => {
-      expect(buildParentPaths([0, 0, 1, 2])).toEqual([
-        'root_0',
-        'root_0_children_0',
-        'root_0_children_0_children_1',
-      ]);
+      expect(buildParentPaths([0, 0, 1, 2])).toEqual(['root_0', 'root_0_children_0', 'root_0_children_0_children_1']);
     });
   });
 

package/lib/shared/pathUtils.ts

@@ -4,69 +4,68 @@
  */
 
 import type { Path } from './paths';
-import { 
-  stringToPath, 
-  pathToLegacyString, 
+import {
+  stringToPath,
+  pathToLegacyString,
   getParentPath as getParentPathArray,
   buildParentPaths as buildParentPathsArray,
-  pathsEqual,
   isRootPath as isRootPathArray,
   ROOT_STRING,
   domPathStringToTreePath,
   treePathToDomPathString,
-  isAncestorPath
+  isAncestorPath,
 } from './paths';
 
 /**
  * Convert a page path to static HTML file path
- * 
+ *
  * @example
  * getStaticFilePath("/") -> "./dist/index.html"
  * getStaticFilePath("/about") -> "./dist/about.html"
  * getStaticFilePath("/blog/post-1") -> "./dist/blog-post-1.html"
  */
-export function getStaticFilePath(pagePath: string, distDir: string = "./dist"): string {
-  if (pagePath === "/") {
+export function getStaticFilePath(pagePath: string, distDir: string = './dist'): string {
+  if (pagePath === '/') {
     return `${distDir}/index.html`;
   }
-  
+
   // Convert /about -> about.html
   // Convert /blog/post-1 -> blog-post-1.html (flat structure)
-  const pathParts = pagePath.substring(1).split("/");
-  const fileName = pathParts.join("-") + ".html";
-  
+  const pathParts = pagePath.substring(1).split('/');
+  const fileName = `${pathParts.join('-')}.html`;
+
   return `${distDir}/${fileName}`;
 }
 
 /**
  * Convert a page path to a page name (for file system)
- * 
+ *
  * @example
  * pathToPageName("/") -> "index"
  * pathToPageName("/about") -> "about"
  */
 export function pathToPageName(pagePath: string): string {
-  return pagePath === "/" ? "index" : pagePath.substring(1);
+  return pagePath === '/' ? 'index' : pagePath.substring(1);
 }
 
 /**
  * Convert a page name to a page path
- * 
+ *
  * @example
  * pageNameToPath("index") -> "/"
  * pageNameToPath("about") -> "/about"
  */
 export function pageNameToPath(pageName: string): string {
-  return pageName === "index" ? "/" : `/${pageName}`;
+  return pageName === 'index' ? '/' : `/${pageName}`;
 }
 
 /**
  * Convert tree path to DOM path
  * The tree adds a synthetic "root" container, so "root_0" in the tree corresponds to "root" in the DOM
  * Also accepts array paths: [0] -> "root", [0,0] -> "root_children_0"
- * 
+ *
  * Uses array operations internally for conversion.
- * 
+ *
  * @example
  * treePathToDomPath("root_0") -> "root"
  * treePathToDomPath("root_0_children_0") -> "root_children_0"
@@ -83,9 +82,9 @@ export function treePathToDomPath(treePath: Path | string): string {
  * Convert DOM path back to tree path
  * The tree adds a synthetic "root" container, so "root" in the DOM corresponds to "root_0" in the tree
  * Returns legacy string format for backward compatibility
- * 
+ *
  * Uses array operations internally for conversion.
- * 
+ *
  * @example
  * domPathToTreePath("root") -> "root_0"
  * domPathToTreePath("root_children_0") -> "root_0_children_0"
@@ -100,18 +99,18 @@ export function domPathToTreePath(domPath: string): string {
  * Build parent paths for expanding tree nodes
  * Returns all parent path segments for a given tree path
  * Also accepts array paths
- * 
+ *
  * @example
  * buildParentPaths("root_0_children_0_children_1") -> ["root_0", "root_0_children_0"]
  * buildParentPaths([0,0,1]) -> ["root_0", "root_0_children_0"]
  */
 export function buildParentPaths(treePath: Path | string): string[] {
   const pathArray = typeof treePath === 'string' ? stringToPath(treePath) : treePath;
-  
+
   if (isRootPathArray(pathArray)) {
     return [];
   }
-  
+
   const parentArrays = buildParentPathsArray(pathArray);
   return parentArrays.map(pathToLegacyString);
 }
@@ -134,43 +133,40 @@ export function getParentPathFromChildPath(childPath: Path | string): string {
  * Convert component instance path to component structure path
  * When editing a component, elements clicked inside the component instance on the page
  * need to be converted to their paths within the component structure.
- * 
+ *
  * Uses array operations internally for path manipulation.
- * 
+ *
  * @example
  * componentInstancePath: "root_children_0" (component instance on page)
  * instancePath: "root_children_0_children_1" (element inside instance)
  * Returns: "root_children_1" (component structure path)
- * 
+ *
  * @param instancePath - Path of element within component instance on page (DOM path string)
  * @param componentInstancePath - Path of the component instance root on the page (DOM path string)
  * @returns Component structure path (always starts with "root")
  */
-export function componentInstancePathToStructurePath(
-  instancePath: string,
-  componentInstancePath: string
-): string {
+export function componentInstancePathToStructurePath(instancePath: string, componentInstancePath: string): string {
   // Convert DOM paths to arrays for manipulation
   const instancePathArray = domPathStringToTreePath(instancePath);
   const componentInstancePathArray = domPathStringToTreePath(componentInstancePath);
-  
+
   // Check if instancePath is inside componentInstancePath using array operations
   if (!isAncestorPath(componentInstancePathArray, instancePathArray)) {
     // Not inside component instance - return as-is (shouldn't happen, but handle gracefully)
     return instancePath;
   }
-  
+
   // Extract relative path using array operations
   // componentInstancePathArray: [0, 0] -> instancePathArray: [0, 0, 1]
   // relative: [1] -> convert to DOM path: "root_children_1"
   const relativePathArray = instancePathArray.slice(componentInstancePathArray.length);
-  
+
   // Convert relative path array back to DOM path string
   // If relative is empty, return root
   if (relativePathArray.length === 0) {
     return ROOT_STRING;
   }
-  
+
   // Build component structure path: root + relative path
   return treePathToDomPathString(relativePathArray);
 }
@@ -179,34 +175,31 @@ export function componentInstancePathToStructurePath(
  * Convert component structure path to component instance path
  * When selecting an element in the component structure tree, convert it to
  * the path within the component instance on the page.
- * 
+ *
  * Uses array operations internally for path manipulation.
- * 
+ *
  * @example
  * componentInstancePath: "root_children_0" (component instance on page)
  * structurePath: "root_children_1" (element in component structure)
  * Returns: "root_children_0_children_1" (path within instance on page)
- * 
+ *
  * @param structurePath - Path within component structure (starts with "root", DOM path string)
  * @param componentInstancePath - Path of the component instance root on the page (DOM path string)
  * @returns Path within component instance on page (DOM path string)
  */
-export function componentStructurePathToInstancePath(
-  structurePath: string,
-  componentInstancePath: string
-): string {
+export function componentStructurePathToInstancePath(structurePath: string, componentInstancePath: string): string {
   // Convert DOM paths to arrays for manipulation
   const structurePathArray = domPathStringToTreePath(structurePath);
   const componentInstancePathArray = domPathStringToTreePath(componentInstancePath);
-  
+
   // Extract relative path from structure path (skip root [0])
   // structurePathArray: [0, 1] -> relative: [1]
   const relativePathArray = structurePathArray.slice(1);
-  
+
   // Combine component instance path with relative path using array operations
   // componentInstancePathArray: [0, 0] + relativePathArray: [1] -> [0, 0, 1]
   const instancePathArray: Path = [...componentInstancePathArray, ...relativePathArray];
-  
+
   // Convert back to DOM path string
   return treePathToDomPathString(instancePathArray);
 }
@@ -214,9 +207,9 @@ export function componentStructurePathToInstancePath(
 /**
  * Convert path for component editing context
  * When editing a component, converts component instance paths to component structure paths
- * 
+ *
  * Uses array operations internally for path manipulation.
- * 
+ *
  * @param path - Path array from canvas
  * @param isEditingComponent - Whether we're editing a component
  * @param componentInstancePath - Path of component instance on page (if editing component, Path array)
@@ -225,7 +218,7 @@ export function componentStructurePathToInstancePath(
 export function convertPathForComponentContext(
   path: Path,
   isEditingComponent: boolean,
-  componentInstancePath: Path | null
+  componentInstancePath: Path | null,
 ): Path {
   if (isEditingComponent && componentInstancePath) {
     // Check if path is inside componentInstancePath using array operations
@@ -233,12 +226,12 @@ export function convertPathForComponentContext(
       // Extract relative path: componentInstancePath: [0, 0] -> path: [0, 0, 1]
       // relative: [1] -> component structure path: [0, 1]
       const relativePath = path.slice(componentInstancePath.length);
-      
+
       // Build component structure path: [0] + relative path
       return [0, ...relativePath];
     }
   }
-  
+
   // Regular page editing - return path as-is
   return path;
 }

package/lib/shared/paths/Path.test.ts

@@ -6,7 +6,7 @@ import {
   ROOT_PREFIX,
   CHILDREN_TOKEN,
   PATH_SEPARATOR,
-  type Path
+  type Path,
 } from './Path';
 
 describe('Path types and constants', () => {
@@ -14,7 +14,7 @@ describe('Path types and constants', () => {
     test('Path is a number array', () => {
       const path: Path = [0, 1, 2];
       expect(Array.isArray(path)).toBe(true);
-      expect(path.every(n => typeof n === 'number')).toBe(true);
+      expect(path.every((n) => typeof n === 'number')).toBe(true);
     });
 
     test('Root path is [0]', () => {

package/lib/shared/paths/Path.ts

@@ -20,4 +20,3 @@ const CHILDREN_TOKEN = 'children';
 const PATH_SEPARATOR = '_';
 
 export { ROOT_PREFIX, CHILDREN_TOKEN, PATH_SEPARATOR };
-

package/lib/shared/paths/PathConverter.test.ts

@@ -5,7 +5,7 @@ import {
   stringToPath,
   pathToLegacyString,
   domPathStringToTreePath,
-  treePathToDomPathString
+  treePathToDomPathString,
 } from './PathConverter';
 import { PathConversionError } from './PathValidator';
 

package/lib/shared/paths/PathConverter.ts

@@ -43,9 +43,9 @@ export function stringToPath(str: string): Path {
   }
 
   // Parse comma-separated format: "0,0,1" -> [0, 0, 1]
-  return str.split(',').map(s => {
+  return str.split(',').map((s) => {
     const num = parseInt(s, 10);
-    if (isNaN(num)) {
+    if (Number.isNaN(num)) {
       throw new PathConversionError(`Invalid numeric index: ${s}`, str);
     }
     return num;
@@ -55,7 +55,7 @@ export function stringToPath(str: string): Path {
 /**
  * Convert array path to legacy string format (for backward compatibility)
  * Converts Path arrays to legacy string format used by TreeNode.path and iframe messages
- * 
+ *
  * @param path - Path array to convert (e.g., [0,0,1])
  * @returns Legacy string path (e.g., "root_0_children_0_children_1")
  */
@@ -63,13 +63,13 @@ export function pathToLegacyString(path: Path): string {
   if (path.length === 0 || (path.length === 1 && path[0] === 0)) {
     return ROOT_0_STRING;
   }
-  
+
   // Build: root_0_children_0_children_1
   let result = ROOT_0_STRING;
   for (let i = 1; i < path.length; i++) {
     result += `${CHILDREN_SEPARATOR}${path[i]}`;
   }
-  
+
   return result;
 }
 
@@ -82,21 +82,19 @@ export function domPathStringToTreePath(domPath: string): Path {
   if (domPath === ROOT_STRING || domPath === '') {
     return [0];
   }
-  
+
   // Remove "root_" prefix and parse
-  const cleanPath = domPath.startsWith(ROOT_PREFIX) 
-    ? domPath.substring(ROOT_PREFIX.length)
-    : domPath;
-  
+  const cleanPath = domPath.startsWith(ROOT_PREFIX) ? domPath.substring(ROOT_PREFIX.length) : domPath;
+
   // Parse "children_0_children_1" -> [0, 1]
   const parts = cleanPath.split(PATH_SEPARATOR);
   const path: Path = [0]; // Tree paths always start with [0]
-  
+
   for (let i = 0; i < parts.length; i++) {
     if (parts[i] === CHILDREN_TOKEN && i + 1 < parts.length) {
-      const indexStr = parts[i + 1];
+      const indexStr = parts[i + 1] ?? '';
       const index = parseInt(indexStr, 10);
-      if (!isNaN(index) && indexStr === String(index)) {
+      if (!Number.isNaN(index) && indexStr === String(index)) {
         // Valid numeric index
         path.push(index);
         i++;
@@ -104,14 +102,14 @@ export function domPathStringToTreePath(domPath: string): Path {
       // Invalid index segments are silently skipped
     }
   }
-  
+
   return path;
 }
 
 /**
  * Convert tree path array to DOM path string
  * Converts Path arrays to DOM path strings used for element registration and highlighting
- * 
+ *
  * @param path - Path array or string (e.g., [0,0,1] or "root_0_children_0_children_1")
  * @returns DOM path string (e.g., "root_children_0_children_1")
  * @throws {InvalidPathError} If path contains invalid values
@@ -122,20 +120,19 @@ export function treePathToDomPathString(path: Path | string): string {
     const pathArray = stringToPath(path);
     return treePathToDomPathString(pathArray);
   }
-  
+
   // Validate path before processing
   validatePath(path);
-  
+
   if (path.length === 0 || (path.length === 1 && path[0] === 0)) {
     return ROOT_STRING;
   }
-  
+
   // Build: root_children_0_children_1
   let result = ROOT_STRING;
   for (let i = 1; i < path.length; i++) {
     result += `${CHILDREN_SEPARATOR}${path[i]}`;
   }
-  
+
   return result;
 }
-