@postxl/generator 1.1.1 → 1.3.0

package/README.md

@@ -79,3 +79,281 @@ This file contains the hash values for each generated file. With this hash value
   the hash in the lock file
 - If the file was changed by the latest generator run: in this case the hash of the newly generated
   file will be different from the hash in the lock file
+
+## File Sync Algorithm
+
+The generator uses a **3-way sync algorithm** to intelligently handle file changes. The three sources are:
+
+1. **Virtual File System (VFS)** - The newly generated content
+2. **Lock File** - Hash values from the previous generation run (`postxl-lock.json`)
+3. **Disk** - The actual files on the filesystem
+
+### State Matrix
+
+| Generated | Lock File | Disk     | Action             | Description                                              |
+| --------- | --------- | -------- | ------------------ | -------------------------------------------------------- |
+| ✓ Changed | Same      | Modified | **Merge Conflict** | File was ejected AND generator template changed          |
+| ✓ Changed | Same      | Same     | Write              | Template changed, file not ejected → auto-update         |
+| ✓ Same    | Same      | Modified | No Action          | File ejected, but template unchanged → keep your changes |
+| ✓ Same    | Same      | Same     | No Action          | Nothing changed                                          |
+| ✓ New     | -         | Exists   | **Merge Conflict** | New generated file conflicts with existing file          |
+| ✓ New     | -         | -        | Write              | Brand new file                                           |
+| - Removed | Exists    | Modified | Delete             | Generator no longer produces this file                   |
+
+### Ejected Files
+
+A file is considered **"ejected"** when you manually modify it. Once ejected:
+
+- The generator will not overwrite your changes automatically
+- If the generator template changes, you'll get a merge conflict to resolve
+- The file remains tracked in `postxl-lock.json` so the generator knows it exists
+
+## Merge Conflicts
+
+When both you and the generator have made changes to the same file, the generator creates Git-style merge conflict markers:
+
+```typescript
+// Unchanged code stays clean
+import { Injectable } from '@nestjs/common'
+
+@Injectable()
+export class UserService {
+<<<<<<< Manual
+  // Your manual changes appear here
+  findAll() {
+    return this.customLogic()
+  }
+=======
+  // Generated version appears here
+  findAll() {
+    return this.repository.findAll()
+  }
+>>>>>>> Generated
+}
+```
+
+### Resolving Merge Conflicts
+
+1. Open the file in your editor
+2. Decide which version to keep (or combine both)
+3. Remove the conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`)
+4. Run the generator again to verify
+
+> **Note**: The generator will refuse to run if there are unresolved merge conflicts in your project (unless `--force` flag is set). Resolve all conflicts before regenerating.
+
+### Force Regeneration
+
+If you want to discard your changes and reset to the generated version:
+
+```bash
+# Force regenerate a specific file
+pnpm run generate -f -p 'backend/libs/types/**/*.ts'
+
+# Force regenerate everything (careful!)
+pnpm run generate -f
+```
+
+## Custom Block Preservation
+
+When you extend generated files with custom code, you can mark your additions with special comment markers. This prevents unnecessary merge conflicts when the generator updates other parts of the file.
+
+### Basic Usage
+
+```typescript
+import { Injectable } from '@nestjs/common'
+
+// @custom-start:imports
+import { CustomLogger } from './logger'
+import { MetricsService } from './metrics'
+// @custom-end:imports
+
+@Injectable()
+export class UserService {
+  constructor(
+    private readonly repository: UserRepository,
+    // @custom-start:dependencies
+    private readonly logger: CustomLogger,
+    private readonly metrics: MetricsService,
+    // @custom-end:dependencies
+  ) {}
+
+  // Generated methods...
+  findAll() {
+    return this.repository.findAll()
+  }
+
+  // @custom-start:customMethods
+  async findAllWithMetrics() {
+    this.metrics.increment('user.findAll')
+    return this.findAll()
+  }
+
+  async customBusinessLogic() {
+    this.logger.log('Custom logic executed')
+    return 'custom result'
+  }
+  // @custom-end:customMethods
+}
+```
+
+### How It Works
+
+When the generator runs and detects custom block markers in an ejected file:
+
+1. **Extract**: Custom blocks are identified and extracted from your modified file
+2. **Compare**: The remaining code (minus custom blocks) is compared to the new generated output
+3. **Reinsert**: Custom blocks are automatically inserted back into the generated output at the same relative position
+4. **Conflict only if needed**: Only actual changes outside your custom blocks will show merge conflict markers
+
+### Marker Syntax
+
+```typescript
+// Line comment style (recommended)
+// @custom-start:blockName
+// ... your custom code ...
+// @custom-end:blockName
+
+// Unnamed blocks (works, but names help with clarity)
+// @custom-start
+// ... your custom code ...
+// @custom-end
+
+// Block comment style (for languages that prefer it)
+/* @custom-start:blockName */
+/* ... your custom code ... */
+/* @custom-end:blockName */
+```
+
+### Block Names
+
+Names are optional but recommended when you have multiple custom blocks:
+
+- Must be alphanumeric with hyphens/underscores: `[a-zA-Z0-9_-]+`
+- Help identify blocks in warnings
+- Opening and closing names should match
+
+### Anchor-Based Positioning
+
+Custom blocks are repositioned based on **anchor context** - the significant code lines immediately before and after your block. For best results:
+
+- Place custom blocks after stable, identifiable lines (method signatures, class declarations, import statements)
+- Avoid placing blocks in areas that frequently change
+- The more unique the surrounding context, the more reliable the repositioning
+
+### When Blocks Cannot Be Placed
+
+If the generator cannot find a suitable position for a custom block (e.g., the surrounding code changed significantly), it will:
+
+1. Append the block at the end of the file
+2. Add a warning comment so you know to move it manually
+
+```typescript
+// ... rest of file ...
+
+// ⚠️ WARNING: The following custom blocks could not be automatically placed.
+// Please manually move them to the appropriate location.
+
+// --- Unplaced custom block: orphanedFeature ---
+// @custom-start:orphanedFeature
+// This code needs to be moved manually
+// @custom-end:orphanedFeature
+```
+
+### Best Practices
+
+1. **Use descriptive names**: `// @custom-start:authMiddleware` is better than `// @custom-start`
+2. **Keep blocks focused**: One feature per block makes them easier to manage
+3. **Place strategically**: Put blocks after stable anchor points
+4. **Don't nest blocks**: Nested custom blocks are not supported
+5. **Match names**: Ensure `@custom-start:foo` has a matching `@custom-end:foo`
+
+### Example: Adding Custom Routes
+
+```typescript
+// Generated router file
+import { Router } from 'express'
+import { getUsers, getUserById, createUser } from './handlers'
+
+const router = Router()
+
+// Generated routes
+router.get('/users', getUsers)
+router.get('/users/:id', getUserById)
+router.post('/users', createUser)
+
+// @custom-start:customRoutes
+// Custom export endpoint
+router.get('/users/export', async (req, res) => {
+  const users = await exportUsersToCSV()
+  res.attachment('users.csv').send(users)
+})
+
+// Custom bulk operations
+router.post('/users/bulk', bulkCreateUsers)
+router.delete('/users/bulk', bulkDeleteUsers)
+// @custom-end:customRoutes
+
+export default router
+```
+
+When the generator adds new routes, your custom routes will be preserved without conflict markers (assuming the anchor context—the generated routes above—remains recognizable).
+
+## CLI Options
+
+```bash
+# Standard generation
+pnpm run generate
+
+# Force regenerate all files (overwrites ejected files)
+pnpm run generate -f
+
+# Force regenerate specific files (glob pattern)
+pnpm run generate -f -p 'backend/libs/types/**/*.ts'
+
+# Show ejected files after generation
+pnpm run generate -e
+
+# Show diff between ejected and generated versions
+pnpm run generate -d
+
+# Watch mode - regenerate on schema changes
+pnpm run generate:watch
+
+# Skip linting and formatting
+pnpm run generate -t
+```
+
+## Troubleshooting
+
+### "Unresolved merge conflicts detected"
+
+The generator found files with conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`). Resolve these manually before running the generator again.
+
+### Custom blocks appearing at end of file
+
+The generator couldn't find the anchor context for your block. This happens when:
+
+- The code before/after your block changed significantly
+- The block was placed in a frequently-changing area
+
+Solution: Move the block back to its correct position and ensure it has stable anchor lines nearby.
+
+### Unexpected merge conflicts in custom block areas
+
+If you're seeing conflicts around custom blocks, check:
+
+- Block markers are properly formatted (`@custom-start`/`@custom-end`)
+- Names match between start and end markers
+- No nested custom blocks
+
+### Lock file out of sync
+
+If `postxl-lock.json` gets out of sync with your files:
+
+```bash
+# Regenerate everything (preserves ejected files unless they conflict)
+pnpm run generate
+
+# Or force regenerate to reset lock file
+pnpm run generate -f
+```

package/dist/helpers/branded.types.d.ts

@@ -31,18 +31,18 @@
  * - `ImportPaths`: FilePath | PackageName
  */
 import z from 'zod';
-declare const zGeneratorInterfaceId: z.ZodBranded<z.ZodString, "PXL.GeneratorInterfaceId">;
+declare const zGeneratorInterfaceId: z.core.$ZodBranded<z.ZodString, "PXL.GeneratorInterfaceId", "out">;
 /**
  * A generator interface id that is used identify what interface a generator implements.
  */
 export type GeneratorInterfaceId = z.infer<typeof zGeneratorInterfaceId>;
-export declare const toGeneratorInterfaceId: (input: string) => string & z.BRAND<"PXL.GeneratorInterfaceId">;
-declare const zTypeName: z.ZodBranded<z.ZodBranded<z.ZodString, "PXL.TypeName">, "PXL.Importable">;
+export declare const toGeneratorInterfaceId: (input: string) => string & z.core.$brand<"PXL.GeneratorInterfaceId">;
+declare const zTypeName: z.core.$ZodBranded<z.core.$ZodBranded<z.ZodString, "PXL.TypeName", "out">, "PXL.Importable", "out">;
 /**
  * A type name that is used to refer to a type in the generated code.
  */
 export type TypeName = z.infer<typeof zTypeName>;
-export declare const toTypeName: (input: string) => string & z.BRAND<"PXL.TypeName"> & z.BRAND<"PXL.Importable">;
+export declare const toTypeName: (input: string) => string & z.core.$brand<"PXL.TypeName"> & z.core.$brand<"PXL.Importable">;
 /**
  * A TypeName that is annotated with the kind of the type.
  * Note: This is used when distinguishing between kinds is required at runtime.
@@ -59,80 +59,80 @@ export declare const toAnnotatedTypeName: (name: TypeName) => AnnotatedTypeName;
  * Type guard to check if a given type is an AnnotatedTypeName.
  */
 export declare const isAnnotatedTypeName: (t: string | AnnotatedTypeName) => t is AnnotatedTypeName;
-declare const zFunctionName: z.ZodBranded<z.ZodBranded<z.ZodString, "PXL.FunctionName">, "PXL.Importable">;
+declare const zFunctionName: z.core.$ZodBranded<z.core.$ZodBranded<z.ZodString, "PXL.FunctionName", "out">, "PXL.Importable", "out">;
 /**
  * A function name that is used to refer to a function in the generated code.
  */
 export type FunctionName = z.infer<typeof zFunctionName>;
-export declare const toFunctionName: (input: string) => string & z.BRAND<"PXL.FunctionName"> & z.BRAND<"PXL.Importable">;
-declare const zVariableName: z.ZodBranded<z.ZodBranded<z.ZodString, "PXL.VariableName">, "PXL.Importable">;
+export declare const toFunctionName: (input: string) => string & z.core.$brand<"PXL.FunctionName"> & z.core.$brand<"PXL.Importable">;
+declare const zVariableName: z.core.$ZodBranded<z.core.$ZodBranded<z.ZodString, "PXL.VariableName", "out">, "PXL.Importable", "out">;
 /**
  * A variable name that is used to refer to a variable in the generated code.
  */
 export type VariableName = z.infer<typeof zVariableName>;
-export declare const toVariableName: (input: string) => string & z.BRAND<"PXL.VariableName"> & z.BRAND<"PXL.Importable">;
-declare const zPostXlPackageName: z.ZodBranded<z.ZodEffects<z.ZodString, string, string>, "PXL.PackageName">;
+export declare const toVariableName: (input: string) => string & z.core.$brand<"PXL.VariableName"> & z.core.$brand<"PXL.Importable">;
+declare const zPostXlPackageName: z.core.$ZodBranded<z.ZodString, "PXL.PackageName", "out">;
 /**
  * A package name that is used to refer to a package in the generated code.
  */
-export declare const toPostXlPackageName: (input: string) => string & z.BRAND<"PXL.PackageName">;
-export declare const toPackageName: (input: string) => string & z.BRAND<"PXL.PackageName">;
+export declare const toPostXlPackageName: (input: string) => string & z.core.$brand<"PXL.PackageName">;
+export declare const toPackageName: (input: string) => string & z.core.$brand<"PXL.PackageName">;
 /**
  * A package name that is used to refer to a package name that is provided via
  * in package.json or is a NodeJS module.
  * E.g. "fs", "random", "@nestjs/common".
  */
 export type PackageName = z.infer<typeof zPostXlPackageName>;
-declare const zClassName: z.ZodBranded<z.ZodBranded<z.ZodString, "PXL.ClassName">, "PXL.Importable">;
+declare const zClassName: z.core.$ZodBranded<z.core.$ZodBranded<z.ZodString, "PXL.ClassName", "out">, "PXL.Importable", "out">;
 /**
  * A class name that is used to refer to a class in the generated code.
  */
 export type ClassName = z.infer<typeof zClassName>;
-export declare const toClassName: (input: string) => string & z.BRAND<"PXL.ClassName"> & z.BRAND<"PXL.Importable">;
-declare const zConstantName: z.ZodBranded<z.ZodBranded<z.ZodString, "PXL.ConstantName">, "PXL.Importable">;
+export declare const toClassName: (input: string) => string & z.core.$brand<"PXL.ClassName"> & z.core.$brand<"PXL.Importable">;
+declare const zConstantName: z.core.$ZodBranded<z.core.$ZodBranded<z.ZodString, "PXL.ConstantName", "out">, "PXL.Importable", "out">;
 /**
  * A constant name that is used to refer to a constant in the generated code.
  */
 export type ConstantName = z.infer<typeof zConstantName>;
-export declare const toConstantName: (input: string) => string & z.BRAND<"PXL.ConstantName"> & z.BRAND<"PXL.Importable">;
-declare const zConstantValue: z.ZodBranded<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>, "PXL.ConstantValue">;
+export declare const toConstantName: (input: string) => string & z.core.$brand<"PXL.ConstantName"> & z.core.$brand<"PXL.Importable">;
+declare const zConstantValue: z.core.$ZodBranded<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>, "PXL.ConstantValue", "out">;
 /**
  * A constant value that is used in the generated code.
  */
 export type ConstantValue = z.infer<typeof zConstantValue>;
-export declare const toConstantValue: (input: string | number | boolean | null) => (string | number | boolean | null) & z.BRAND<"PXL.ConstantValue">;
-declare const zDiscriminantValue: z.ZodBranded<z.ZodString, "PXL.DiscriminantValue">;
+export declare const toConstantValue: (input: string | number | boolean | null) => (string & z.core.$brand<"PXL.ConstantValue">) | (number & z.core.$brand<"PXL.ConstantValue">) | (false & z.core.$brand<"PXL.ConstantValue">) | (true & z.core.$brand<"PXL.ConstantValue">);
+declare const zDiscriminantValue: z.core.$ZodBranded<z.ZodString, "PXL.DiscriminantValue", "out">;
 /**
  * A discriminant value, used to discriminate union types.
  */
 export type DiscriminantValue = z.infer<typeof zDiscriminantValue>;
-export declare const toDiscriminantValue: (input: string) => string & z.BRAND<"PXL.DiscriminantValue">;
-declare const zFileName: z.ZodBranded<z.ZodString, "PXL.FileName">;
+export declare const toDiscriminantValue: (input: string) => string & z.core.$brand<"PXL.DiscriminantValue">;
+declare const zFileName: z.core.$ZodBranded<z.ZodString, "PXL.FileName", "out">;
 /**
  * A file name that is used to refer to a file in the generated code.
  */
 export type FileName = z.infer<typeof zFileName>;
-export declare const toFileName: (input: string) => string & z.BRAND<"PXL.FileName">;
-declare const zFolderName: z.ZodBranded<z.ZodString, "PXL.FolderName">;
+export declare const toFileName: (input: string) => string & z.core.$brand<"PXL.FileName">;
+declare const zFolderName: z.core.$ZodBranded<z.ZodString, "PXL.FolderName", "out">;
 /**
  * A folder name that is used to refer to a folder in the generated code.
  */
 export type FolderName = z.infer<typeof zFolderName>;
-export declare const toFolderName: (input: string) => string & z.BRAND<"PXL.FolderName">;
-declare const zFilePath: z.ZodBranded<z.ZodString, "PXL.FilePath">;
+export declare const toFolderName: (input: string) => string & z.core.$brand<"PXL.FolderName">;
+declare const zFilePath: z.core.$ZodBranded<z.ZodString, "PXL.FilePath", "out">;
 /**
  * A file path that is used to refer to a file in the generated code.
  */
 export type FilePath = z.infer<typeof zFilePath>;
-export declare const toFilePath: (input: string) => string & z.BRAND<"PXL.FilePath">;
-declare const zBackendModuleName: z.ZodBranded<z.ZodString, "PXL.BackendModuleName">;
+export declare const toFilePath: (input: string) => string & z.core.$brand<"PXL.FilePath">;
+declare const zBackendModuleName: z.core.$ZodBranded<z.ZodString, "PXL.BackendModuleName", "out">;
 /**
  * A backend module name that is used to refer to a module in the backend.
  * E.g. `@actions`.
  */
 export type BackendModuleName = z.infer<typeof zBackendModuleName>;
-export declare const toBackendModuleName: (input: string) => string & z.BRAND<"PXL.BackendModuleName">;
-declare const zBackendModuleLocation: z.ZodBranded<z.ZodString, "PXL.BackendModuleLocation">;
+export declare const toBackendModuleName: (input: string) => string & z.core.$brand<"PXL.BackendModuleName">;
+declare const zBackendModuleLocation: z.core.$ZodBranded<z.ZodString, "PXL.BackendModuleLocation", "out">;
 /**
  * A module location is a reference to a file in a locale backend module.
  * E.g. `@actions/actions.types`.
@@ -143,7 +143,7 @@ declare const zBackendModuleLocation: z.ZodBranded<z.ZodString, "PXL.BackendModu
  * Therefore, we need to reference the actual file together with the package name.
  */
 export type BackendModuleLocation = z.infer<typeof zBackendModuleLocation>;
-export declare const toBackendModuleLocation: (input: `@${string}`) => string & z.BRAND<"PXL.BackendModuleLocation">;
+export declare const toBackendModuleLocation: (input: `@${string}`) => string & z.core.$brand<"PXL.BackendModuleLocation">;
 export type ImportableTypes = TypeName | FunctionName | ClassName | ConstantName | AnnotatedTypeName;
 export type ImportPaths = FilePath | PackageName | BackendModuleLocation;
 export {};

package/dist/helpers/branded.types.js

@@ -64,7 +64,9 @@ const toVariableName = (input) => zVariableName.parse(input);
 exports.toVariableName = toVariableName;
 const zPostXlPackageName = zod_1.default
     .string()
-    .refine((name) => name.startsWith('@postxl/'), (name) => ({ message: `Package name must start with "@postxl/", got "${name}"!` }))
+    .refine((name) => name.startsWith('@postxl/'), {
+    error: (issue) => `Package name must start with "@postxl/", got "${issue.input}"!`,
+})
     .brand('PXL.PackageName');
 /**
  * A package name that is used to refer to a package in the generated code.

package/dist/utils/checksum.d.ts

@@ -1,5 +1,5 @@
 import z from 'zod';
-export declare const zChecksum: z.ZodBranded<z.ZodString, "PXL.Checksum">;
+export declare const zChecksum: z.core.$ZodBranded<z.ZodString, "PXL.Checksum", "out">;
 /**
  * Branded Id type that should be used to identify checksum strings.
  */

package/dist/utils/custom-blocks.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Custom Block Preservation for Merge Conflicts
+ *
+ * This module provides functionality to preserve custom code blocks during
+ * merge conflict generation. Developers can mark sections of code with special
+ * comment markers, and these sections will be automatically preserved when
+ * the generator runs.
+ *
+ * ## Usage
+ *
+ * Mark custom code blocks in your ejected files:
+ *
+ * ```typescript
+ * // @custom-start
+ * // your custom code here
+ * // @custom-end
+ *
+ * // Or with a name for clarity:
+ * // @custom-start:myFeature
+ * // your custom code here
+ * // @custom-end:myFeature
+ * ```
+ *
+ * When the generator runs and would normally create merge conflicts,
+ * it will:
+ * 1. Extract custom blocks from the modified file
+ * 2. Find appropriate anchor points in the generated content
+ * 3. Re-insert custom blocks at the correct positions
+ * 4. Only create merge conflict markers for actual conflicts
+ */
+/**
+ * Marker patterns for custom blocks
+ *
+ * Supported formats:
+ * - Line comments: // @custom-start or // @custom-start:name
+ * - Block comments: Must be on a single line with both delimiters
+ *
+ * Note: Multi-line block comments are NOT supported. The opening and closing
+ * delimiters must be on the same line as the marker. This simplifies parsing
+ * and avoids ambiguity. See tests for examples.
+ */
+export declare const customBlockMarkers: {
+    readonly startPattern: RegExp;
+    readonly endPattern: RegExp;
+};
+/**
+ * Represents a custom block extracted from source code
+ */
+export type CustomBlock = {
+    /** Optional name of the block (from @custom-start:name) */
+    name: string | undefined;
+    /** The lines of content within the block (including markers) */
+    lines: string[];
+    /** The line index where the block starts (0-based) */
+    startLineIndex: number;
+    /** The line index where the block ends (0-based, inclusive) */
+    endLineIndex: number;
+    /** Anchor context: non-empty lines before the block for positioning */
+    anchorBefore: string[];
+    /** Anchor context: non-empty lines after the block for positioning */
+    anchorAfter: string[];
+};
+/**
+ * Result of extracting custom blocks from source code
+ */
+export type ExtractResult = {
+    /** Successfully extracted custom blocks */
+    blocks: CustomBlock[];
+    /** Lines that are not part of any custom block */
+    nonCustomLines: string[];
+    /** Indices of non-custom lines in the original source */
+    nonCustomLineIndices: number[];
+    /** Any errors encountered during extraction */
+    errors: CustomBlockError[];
+};
+export type CustomBlockError = {
+    type: 'unclosed_block' | 'unexpected_end' | 'mismatched_name';
+    message: string;
+    lineIndex: number;
+};
+/**
+ * Extracts custom blocks from source code content.
+ *
+ * @param content - The source code content as a string
+ * @returns ExtractResult containing blocks, non-custom lines, and any errors
+ */
+export declare function extractCustomBlocks(content: string): ExtractResult;
+/**
+ * Finds the best position to insert a custom block in the target content
+ * based on anchor context matching.
+ *
+ * @param block - The custom block to insert
+ * @param targetLines - The target content lines
+ * @returns The line index where the block should be inserted, or null if no good position found
+ */
+export declare function findInsertionPosition(block: CustomBlock, targetLines: string[]): number | null;
+/**
+ * Inserts custom blocks into the target content at their appropriate positions.
+ *
+ * @param blocks - The custom blocks to insert
+ * @param targetContent - The target content to insert blocks into
+ * @returns Object containing the modified content and any blocks that couldn't be placed
+ */
+export declare function insertCustomBlocks(blocks: CustomBlock[], targetContent: string): {
+    content: string;
+    unplacedBlocks: CustomBlock[];
+};
+/**
+ * Checks if a string contains any custom block markers
+ */
+export declare function hasCustomBlockMarkers(content: string): boolean;
+/**
+ * Reconstructs content from non-custom lines, used when comparing
+ * the "real" content differences (excluding custom blocks)
+ */
+export declare function reconstructNonCustomContent(extractResult: ExtractResult): string;

package/dist/utils/custom-blocks.js

@@ -0,0 +1,454 @@
+"use strict";
+/**
+ * Custom Block Preservation for Merge Conflicts
+ *
+ * This module provides functionality to preserve custom code blocks during
+ * merge conflict generation. Developers can mark sections of code with special
+ * comment markers, and these sections will be automatically preserved when
+ * the generator runs.
+ *
+ * ## Usage
+ *
+ * Mark custom code blocks in your ejected files:
+ *
+ * ```typescript
+ * // @custom-start
+ * // your custom code here
+ * // @custom-end
+ *
+ * // Or with a name for clarity:
+ * // @custom-start:myFeature
+ * // your custom code here
+ * // @custom-end:myFeature
+ * ```
+ *
+ * When the generator runs and would normally create merge conflicts,
+ * it will:
+ * 1. Extract custom blocks from the modified file
+ * 2. Find appropriate anchor points in the generated content
+ * 3. Re-insert custom blocks at the correct positions
+ * 4. Only create merge conflict markers for actual conflicts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.customBlockMarkers = void 0;
+exports.extractCustomBlocks = extractCustomBlocks;
+exports.findInsertionPosition = findInsertionPosition;
+exports.insertCustomBlocks = insertCustomBlocks;
+exports.hasCustomBlockMarkers = hasCustomBlockMarkers;
+exports.reconstructNonCustomContent = reconstructNonCustomContent;
+/**
+ * Marker patterns for custom blocks
+ *
+ * Supported formats:
+ * - Line comments: // @custom-start or // @custom-start:name
+ * - Block comments: Must be on a single line with both delimiters
+ *
+ * Note: Multi-line block comments are NOT supported. The opening and closing
+ * delimiters must be on the same line as the marker. This simplifies parsing
+ * and avoids ambiguity. See tests for examples.
+ */
+exports.customBlockMarkers = {
+    // Matches: // @custom-start or // @custom-start:name
+    // Also supports: /* @custom-start */ or /* @custom-start:name */
+    startPattern: /^\s*(?:\/\/|\/\*)\s*@custom-start(?::([a-zA-Z0-9_-]+))?\s*(?:\*\/)?\s*$/,
+    // Matches: // @custom-end or // @custom-end:name
+    // Also supports: /* @custom-end */ or /* @custom-end:name */
+    endPattern: /^\s*(?:\/\/|\/\*)\s*@custom-end(?::([a-zA-Z0-9_-]+))?\s*(?:\*\/)?\s*$/,
+};
+/**
+ * Number of non-empty lines to capture before/after a custom block for anchoring
+ */
+const ANCHOR_CONTEXT_LINES = 3;
+/**
+ * Extracts the block name from a regex match result
+ */
+function extractBlockName(match) {
+    return match[1] ?? undefined;
+}
+/**
+ * Processes a @custom-start marker
+ */
+function processStartMarker(line, lineIndex, startMatch, currentBlock, errors) {
+    if (!currentBlock) {
+        // Starting a new custom block
+        return {
+            name: extractBlockName(startMatch),
+            lines: [line],
+            startLineIndex: lineIndex,
+        };
+    }
+    // Nested @custom-start - this is an error
+    errors.push({
+        type: 'unclosed_block',
+        message: `Found @custom-start while already inside a custom block${currentBlock.name ? ` (${currentBlock.name})` : ''}. Nested custom blocks are not supported.`,
+        lineIndex,
+    });
+    currentBlock.lines.push(line);
+    return currentBlock;
+}
+/**
+ * Processes a @custom-end marker
+ * Always returns null since processing an end marker closes the current block
+ */
+function processEndMarker(line, lineIndex, endMatch, currentBlock, lines, blocks, errors) {
+    if (!currentBlock) {
+        // @custom-end without a matching start
+        errors.push({
+            type: 'unexpected_end',
+            message: `Found @custom-end without a matching @custom-start`,
+            lineIndex,
+        });
+        return null;
+    }
+    const endName = extractBlockName(endMatch);
+    // Check for name mismatch
+    if (currentBlock.name !== endName) {
+        errors.push({
+            type: 'mismatched_name',
+            message: `Custom block name mismatch: started with "${currentBlock.name ?? '(unnamed)'}" but ended with "${endName ?? '(unnamed)'}"`,
+            lineIndex,
+        });
+    }
+    currentBlock.lines.push(line);
+    // Capture anchor context
+    const anchorBefore = captureAnchorContext(lines, currentBlock.startLineIndex, 'before');
+    const anchorAfter = captureAnchorContext(lines, lineIndex, 'after');
+    blocks.push({
+        name: currentBlock.name,
+        lines: currentBlock.lines,
+        startLineIndex: currentBlock.startLineIndex,
+        endLineIndex: lineIndex,
+        anchorBefore,
+        anchorAfter,
+    });
+    return null;
+}
+/**
+ * Adds unclosed block's lines to non-custom lines
+ */
+function processUnclosedBlock(currentBlock, nonCustomLines, nonCustomLineIndices, errors) {
+    errors.push({
+        type: 'unclosed_block',
+        message: `Custom block${currentBlock.name ? ` (${currentBlock.name})` : ''} was never closed`,
+        lineIndex: currentBlock.startLineIndex,
+    });
+    // Add the unclosed block's lines to non-custom lines
+    for (let i = 0; i < currentBlock.lines.length; i++) {
+        const blockLine = currentBlock.lines[i];
+        if (blockLine === undefined) {
+            continue;
+        }
+        nonCustomLines.push(blockLine);
+        nonCustomLineIndices.push(currentBlock.startLineIndex + i);
+    }
+}
+/**
+ * Extracts custom blocks from source code content.
+ *
+ * @param content - The source code content as a string
+ * @returns ExtractResult containing blocks, non-custom lines, and any errors
+ */
+function extractCustomBlocks(content) {
+    const lines = content.split('\n');
+    const blocks = [];
+    const errors = [];
+    const nonCustomLines = [];
+    const nonCustomLineIndices = [];
+    let currentBlock = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined) {
+            continue;
+        }
+        const startMatch = exports.customBlockMarkers.startPattern.exec(line);
+        const endMatch = exports.customBlockMarkers.endPattern.exec(line);
+        if (startMatch) {
+            currentBlock = processStartMarker(line, i, startMatch, currentBlock, errors);
+        }
+        else if (endMatch) {
+            const wasInBlock = currentBlock !== null;
+            currentBlock = processEndMarker(line, i, endMatch, currentBlock, lines, blocks, errors);
+            // If we weren't in a block, this line goes to non-custom lines
+            if (!wasInBlock) {
+                nonCustomLines.push(line);
+                nonCustomLineIndices.push(i);
+            }
+        }
+        else if (currentBlock) {
+            // Inside a custom block, add to current block's lines
+            currentBlock.lines.push(line);
+        }
+        else {
+            // Not inside a custom block
+            nonCustomLines.push(line);
+            nonCustomLineIndices.push(i);
+        }
+    }
+    // Check for unclosed block at end of file
+    if (currentBlock) {
+        processUnclosedBlock(currentBlock, nonCustomLines, nonCustomLineIndices, errors);
+    }
+    return { blocks, nonCustomLines, nonCustomLineIndices, errors };
+}
+/**
+ * Captures anchor context lines (non-empty, significant lines) before or after a position
+ */
+function captureAnchorContext(lines, position, direction) {
+    const anchors = [];
+    const step = direction === 'before' ? -1 : 1;
+    const start = direction === 'before' ? position - 1 : position + 1;
+    for (let i = start; direction === 'before' ? i >= 0 : i < lines.length; i += step) {
+        const line = lines[i];
+        if (line === undefined) {
+            continue;
+        }
+        // Skip empty lines and custom block markers
+        if (isSignificantLine(line)) {
+            anchors.push(normalizeAnchorLine(line));
+            if (anchors.length >= ANCHOR_CONTEXT_LINES) {
+                break;
+            }
+        }
+    }
+    // Reverse "before" anchors so they're in original order (closest to block first)
+    if (direction === 'before') {
+        anchors.reverse();
+    }
+    return anchors;
+}
+/**
+ * Checks if a line is significant for anchoring purposes
+ * (not empty, not a comment-only line, not a custom block marker)
+ */
+function isSignificantLine(line) {
+    const trimmed = line.trim();
+    if (trimmed === '') {
+        return false;
+    }
+    if (exports.customBlockMarkers.startPattern.test(line)) {
+        return false;
+    }
+    if (exports.customBlockMarkers.endPattern.test(line)) {
+        return false;
+    }
+    // Consider all other lines significant (including comments that might be documentation)
+    return true;
+}
+/**
+ * Normalizes a line for anchor comparison (trims whitespace)
+ */
+function normalizeAnchorLine(line) {
+    return line.trim();
+}
+/**
+ * Finds the best position to insert a custom block in the target content
+ * based on anchor context matching.
+ *
+ * @param block - The custom block to insert
+ * @param targetLines - The target content lines
+ * @returns The line index where the block should be inserted, or null if no good position found
+ */
+function findInsertionPosition(block, targetLines) {
+    // Strategy 1: Try to find a match using "before" anchors
+    // We look for the anchor sequence and insert after the last matched anchor
+    const beforePosition = findAnchorSequence(block.anchorBefore, targetLines, 'before');
+    if (beforePosition !== null) {
+        return beforePosition + 1; // Insert after the anchor
+    }
+    // Strategy 2: Try to find a match using "after" anchors
+    // We look for the anchor sequence and insert before the first matched anchor
+    const afterPosition = findAnchorSequence(block.anchorAfter, targetLines, 'after');
+    if (afterPosition !== null) {
+        return afterPosition; // Insert before the anchor
+    }
+    // Strategy 3: Try to find any single anchor match
+    const singleAnchor = findSingleAnchorMatch(block, targetLines);
+    if (singleAnchor !== null) {
+        return singleAnchor;
+    }
+    return null;
+}
+/**
+ * Finds a sequence of anchor lines in the target content
+ */
+function findAnchorSequence(anchors, targetLines, mode) {
+    if (anchors.length === 0) {
+        return null;
+    }
+    // For "before" mode, we want to find the sequence and return the position of the last anchor
+    // For "after" mode, we want to find the sequence and return the position of the first anchor
+    // Try to match progressively fewer anchors (from all to just one)
+    for (let matchCount = anchors.length; matchCount >= 1; matchCount--) {
+        const anchorsToMatch = mode === 'before'
+            ? anchors.slice(-matchCount) // Take last N anchors for "before"
+            : anchors.slice(0, matchCount); // Take first N anchors for "after"
+        const position = findSequenceInTarget(anchorsToMatch, targetLines, mode);
+        if (position !== null) {
+            return position;
+        }
+    }
+    return null;
+}
+/**
+ * Finds the next significant line index starting from a given position
+ */
+function findNextSignificantLineIndex(targetLines, startIndex) {
+    for (let i = startIndex; i < targetLines.length; i++) {
+        const line = targetLines[i];
+        if (line !== undefined && isSignificantLine(line)) {
+            return i;
+        }
+    }
+    return null;
+}
+/**
+ * Checks if a sequence matches at a given position in target lines
+ */
+function matchSequenceAtPosition(sequence, targetLines, startIndex) {
+    let lastMatchIndex = startIndex;
+    for (let j = 1; j < sequence.length; j++) {
+        const expectedAnchor = sequence[j];
+        if (expectedAnchor === undefined) {
+            return { matches: false, lastMatchIndex };
+        }
+        // Find the next significant line in target
+        const nextIndex = findNextSignificantLineIndex(targetLines, lastMatchIndex + 1);
+        if (nextIndex === null) {
+            return { matches: false, lastMatchIndex };
+        }
+        const nextTargetLine = targetLines[nextIndex];
+        if (nextTargetLine === undefined || normalizeAnchorLine(nextTargetLine) !== expectedAnchor) {
+            return { matches: false, lastMatchIndex };
+        }
+        lastMatchIndex = nextIndex;
+    }
+    return { matches: true, lastMatchIndex };
+}
+/**
+ * Finds a specific sequence of lines in the target
+ */
+function findSequenceInTarget(sequence, targetLines, mode) {
+    if (sequence.length === 0) {
+        return null;
+    }
+    const firstAnchor = sequence[0];
+    if (firstAnchor === undefined) {
+        return null;
+    }
+    for (let i = 0; i < targetLines.length; i++) {
+        const targetLine = targetLines[i];
+        if (targetLine === undefined) {
+            continue;
+        }
+        if (normalizeAnchorLine(targetLine) === firstAnchor) {
+            const { matches, lastMatchIndex } = matchSequenceAtPosition(sequence, targetLines, i);
+            if (matches) {
+                return mode === 'before' ? lastMatchIndex : i;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Finds a single anchor in target lines
+ */
+function findAnchorInTarget(anchor, targetLines) {
+    for (let i = 0; i < targetLines.length; i++) {
+        const targetLine = targetLines[i];
+        if (targetLine === undefined) {
+            continue;
+        }
+        if (normalizeAnchorLine(targetLine) === anchor) {
+            return i;
+        }
+    }
+    return null;
+}
+/**
+ * Finds a single anchor match as a fallback
+ */
+function findSingleAnchorMatch(block, targetLines) {
+    // Try "before" anchors first (prefer closest anchor)
+    for (let i = block.anchorBefore.length - 1; i >= 0; i--) {
+        const anchor = block.anchorBefore[i];
+        if (anchor === undefined) {
+            continue;
+        }
+        const position = findAnchorInTarget(anchor, targetLines);
+        if (position !== null) {
+            return position + 1; // Insert after this anchor
+        }
+    }
+    // Try "after" anchors
+    for (const anchor of block.anchorAfter) {
+        const position = findAnchorInTarget(anchor, targetLines);
+        if (position !== null) {
+            return position; // Insert before this anchor
+        }
+    }
+    return null;
+}
+/**
+ * Inserts custom blocks into the target content at their appropriate positions.
+ *
+ * @param blocks - The custom blocks to insert
+ * @param targetContent - The target content to insert blocks into
+ * @returns Object containing the modified content and any blocks that couldn't be placed
+ */
+function insertCustomBlocks(blocks, targetContent) {
+    if (blocks.length === 0) {
+        return { content: targetContent, unplacedBlocks: [] };
+    }
+    const targetLines = targetContent.split('\n');
+    const unplacedBlocks = [];
+    // Sort blocks by their insertion position (reverse order to maintain indices)
+    const blocksWithPositions = blocks.map((block) => ({
+        block,
+        position: findInsertionPosition(block, targetLines),
+    }));
+    // Separate placed and unplaced blocks
+    const placedBlocks = blocksWithPositions
+        .filter((b) => b.position !== null)
+        .sort((a, b) => b.position - a.position); // Sort descending to insert from end
+    for (const { block, position } of blocksWithPositions) {
+        if (position === null) {
+            unplacedBlocks.push(block);
+        }
+    }
+    // Insert blocks from end to beginning to maintain correct positions
+    for (const { block, position } of placedBlocks) {
+        // Add an empty line before the block if the previous line is not empty
+        const prevLine = position > 0 ? targetLines[position - 1] : undefined;
+        const needsEmptyLineBefore = prevLine !== undefined && prevLine.trim() !== '';
+        // Add an empty line after the block if the next line is not empty
+        const nextLine = position < targetLines.length ? targetLines[position] : undefined;
+        const needsEmptyLineAfter = nextLine !== undefined && nextLine.trim() !== '';
+        const insertLines = [];
+        if (needsEmptyLineBefore) {
+            insertLines.push('');
+        }
+        insertLines.push(...block.lines);
+        if (needsEmptyLineAfter) {
+            insertLines.push('');
+        }
+        targetLines.splice(position, 0, ...insertLines);
+    }
+    return {
+        content: targetLines.join('\n'),
+        unplacedBlocks,
+    };
+}
+/**
+ * Checks if a string contains any custom block markers
+ */
+function hasCustomBlockMarkers(content) {
+    const lines = content.split('\n');
+    return lines.some((line) => exports.customBlockMarkers.startPattern.test(line) || exports.customBlockMarkers.endPattern.test(line));
+}
+/**
+ * Reconstructs content from non-custom lines, used when comparing
+ * the "real" content differences (excluding custom blocks)
+ */
+function reconstructNonCustomContent(extractResult) {
+    return extractResult.nonCustomLines.join('\n');
+}

package/dist/utils/index.d.ts

@@ -1,3 +1,4 @@
+export * from './custom-blocks';
 export * from './jsdoc';
 export * from './lint';
 export * from './path';

package/dist/utils/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./custom-blocks"), exports);
 __exportStar(require("./jsdoc"), exports);
 __exportStar(require("./lint"), exports);
 __exportStar(require("./path"), exports);

package/dist/utils/lockfile.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { VirtualFileSystem } from './vfs.class';
-declare const zLockFile: z.ZodEffects<z.ZodRecord<z.ZodBranded<z.ZodString, "PXL.PosixPath">, z.ZodBranded<z.ZodString, "PXL.Checksum">>, Map<string & z.BRAND<"PXL.PosixPath">, string & z.BRAND<"PXL.Checksum">>, Record<string, string>>;
+declare const zLockFile: z.ZodPipe<z.ZodRecord<z.core.$ZodBranded<z.ZodString, "PXL.PosixPath", "out">, z.core.$ZodBranded<z.ZodString, "PXL.Checksum", "out">>, z.ZodTransform<Map<string & z.core.$brand<"PXL.PosixPath">, string & z.core.$brand<"PXL.Checksum">>, Record<string & z.core.$brand<"PXL.PosixPath">, string & z.core.$brand<"PXL.Checksum">>>>;
 type LockFile = z.infer<typeof zLockFile>;
 export declare function writeLockFile(lockFilePath: string, vfs: VirtualFileSystem): Promise<void>;
 export declare function readLockFile(lockFilePath: string): Promise<LockFile | undefined>;

package/dist/utils/merge-conflict.d.ts

@@ -17,11 +17,23 @@ export declare function hasMergeConflictMarkers(content: FileContent): boolean;
 /**
  * Generates a merged output with conflict markers between two file contents.
  *
+ * This function supports custom block preservation: if the source content contains
+ * custom blocks marked with `// @custom-start` and `// @custom-end` comments,
+ * those blocks will be automatically inserted into the generated content at their
+ * appropriate positions (based on anchor context), avoiding unnecessary merge conflicts
+ * for custom code that was intentionally added.
+ *
  * @param contentSource - The content of the first file as a string.
  * @param contentIncoming - The content of the second file as a string.
  * @param labelSource - Optional label for the first file in conflict markers.
  * @param labelIncoming - Optional label for the second file in conflict markers.
  * @returns The merged content with conflict markers as a string.
+ *
+ * @example
+ * // Mark custom code in ejected files:
+ * // @custom-start:myFeature
+ * // your custom code here
+ * // @custom-end:myFeature
  */
 export declare function generateMergeConflict({ contentSource, contentIncoming, labelSource, labelIncoming, }: {
     contentSource: FileContent;

package/dist/utils/merge-conflict.js

@@ -39,6 +39,7 @@ exports.generateMergeConflict = generateMergeConflict;
 exports.generateDiffSummary = generateDiffSummary;
 const Diff = __importStar(require("diff"));
 const utils_1 = require("@postxl/utils");
+const custom_blocks_1 = require("./custom-blocks");
 /**
  * Standard merge conflict markers used by git and our generator
  */
@@ -84,6 +85,28 @@ function normalizeWhitespace(content) {
     }
     return lines.join('\n');
 }
+/**
+ * Normalizes whitespace more aggressively for semantic comparison.
+ * Used when comparing content with custom blocks removed to check if there are real differences.
+ * - All whitespace normalization from normalizeWhitespace
+ * - Removes ALL empty lines (only compares non-empty content)
+ * - Trims each line
+ *
+ * This aggressive approach is appropriate because when users add custom blocks,
+ * they often add empty lines before/after for formatting. These empty lines
+ * should not be considered "real differences" when the custom block is removed.
+ */
+function normalizeForSemanticComparison(content) {
+    const normalized = content
+        .replaceAll('\r\n', '\n')
+        .replaceAll('\n\r', '\n')
+        .replaceAll('\r', '\n')
+        .replaceAll('\uFEFF', '');
+    const lines = normalized.split('\n').map((line) => line.trimEnd());
+    // Keep only non-empty lines for comparison
+    const nonEmptyLines = lines.filter((line) => line.trim() !== '');
+    return nonEmptyLines.join('\n');
+}
 /**
  * Checks if two arrays of lines differ only in whitespace/spacing
  */
@@ -95,11 +118,23 @@ function isWhitespaceOnlyDifference(sourceLines, incomingLines) {
 /**
  * Generates a merged output with conflict markers between two file contents.
  *
+ * This function supports custom block preservation: if the source content contains
+ * custom blocks marked with `// @custom-start` and `// @custom-end` comments,
+ * those blocks will be automatically inserted into the generated content at their
+ * appropriate positions (based on anchor context), avoiding unnecessary merge conflicts
+ * for custom code that was intentionally added.
+ *
  * @param contentSource - The content of the first file as a string.
  * @param contentIncoming - The content of the second file as a string.
  * @param labelSource - Optional label for the first file in conflict markers.
  * @param labelIncoming - Optional label for the second file in conflict markers.
  * @returns The merged content with conflict markers as a string.
+ *
+ * @example
+ * // Mark custom code in ejected files:
+ * // @custom-start:myFeature
+ * // your custom code here
+ * // @custom-end:myFeature
  */
 function generateMergeConflict({ contentSource, contentIncoming, labelSource = 'Manual', labelIncoming = 'Generated', }) {
     // In case the content is binary, we just return the incoming content
@@ -113,6 +148,92 @@ function generateMergeConflict({ contentSource, contentIncoming, labelSource = '
     if (sourceNormalized === incomingNormalized) {
         return contentIncoming;
     }
+    // Handle custom blocks: extract from source, insert into incoming
+    if ((0, custom_blocks_1.hasCustomBlockMarkers)(contentSource)) {
+        return generateMergeConflictWithCustomBlocks({
+            contentSource,
+            contentIncoming,
+            labelSource,
+            labelIncoming,
+        });
+    }
+    // Standard merge conflict generation (no custom blocks)
+    return generateStandardMergeConflict({
+        contentSource,
+        contentIncoming,
+        labelSource,
+        labelIncoming,
+    });
+}
+/**
+ * Generates merge conflict output while preserving custom blocks.
+ *
+ * The algorithm:
+ * 1. Extract custom blocks from the source (manual) content
+ * 2. Compare source (minus custom blocks) with original incoming to check for real conflicts
+ * 3. If no real conflicts, insert custom blocks into incoming and return without conflict markers
+ * 4. If real conflicts exist, insert custom blocks into incoming and generate merge conflict
+ *    between source (minus custom blocks) and modified incoming
+ */
+function generateMergeConflictWithCustomBlocks({ contentSource, contentIncoming, labelSource, labelIncoming, }) {
+    // Extract custom blocks from source
+    const extractResult = (0, custom_blocks_1.extractCustomBlocks)(contentSource);
+    if (extractResult.blocks.length === 0) {
+        // No valid custom blocks found, fall back to standard merge conflict
+        return generateStandardMergeConflict({
+            contentSource,
+            contentIncoming,
+            labelSource,
+            labelIncoming,
+        });
+    }
+    // Reconstruct source content without custom blocks
+    const sourceWithoutCustomBlocks = (0, custom_blocks_1.reconstructNonCustomContent)(extractResult);
+    // Compare source (minus custom blocks) with original incoming to check for real conflicts
+    // If they match, the only difference was the custom blocks, so no conflict needed
+    // Use semantic comparison which is more lenient about empty line differences
+    const sourceNormalized = normalizeForSemanticComparison(sourceWithoutCustomBlocks);
+    const incomingNormalized = normalizeForSemanticComparison(contentIncoming);
+    // Insert custom blocks into incoming content
+    const { content: incomingWithCustomBlocks, unplacedBlocks } = (0, custom_blocks_1.insertCustomBlocks)(extractResult.blocks, contentIncoming);
+    if (sourceNormalized === incomingNormalized) {
+        // No conflicts outside of custom blocks - just return incoming with custom blocks
+        return handleUnplacedBlocks(incomingWithCustomBlocks, unplacedBlocks);
+    }
+    // There are real conflicts outside of custom blocks
+    // Generate merge conflict between source (minus custom blocks) and incoming-with-custom-blocks
+    // This way, the custom blocks appear on the "Generated" side of any conflicts
+    const mergeResult = generateStandardMergeConflict({
+        contentSource: sourceWithoutCustomBlocks,
+        contentIncoming: incomingWithCustomBlocks,
+        labelSource,
+        labelIncoming,
+    });
+    return handleUnplacedBlocks(mergeResult, unplacedBlocks);
+}
+/**
+ * Appends unplaced custom blocks at the end of the content with a warning comment
+ */
+function handleUnplacedBlocks(content, unplacedBlocks) {
+    if (unplacedBlocks.length === 0) {
+        return content;
+    }
+    let result = content.trimEnd();
+    result += '\n\n';
+    result += '// ⚠️ WARNING: The following custom blocks could not be automatically placed.\n';
+    result += '// Please manually move them to the appropriate location.\n';
+    for (const block of unplacedBlocks) {
+        result += '\n';
+        result += `// --- Unplaced custom block${block.name ? `: ${block.name}` : ''} ---\n`;
+        result += block.lines.join('\n');
+        result += '\n';
+    }
+    return result;
+}
+/**
+ * Standard merge conflict generation without custom block handling
+ */
+function generateStandardMergeConflict({ contentSource, contentIncoming, labelSource, labelIncoming, }) {
     const blocks = new Blocks({ source: contentSource, incoming: contentIncoming });
     let result = '';
     for (const block of blocks.blocks) {
@@ -131,9 +252,13 @@ function generateMergeConflict({ contentSource, contentIncoming, labelSource = '
         }
         // Real content difference - create conflict markers
         result += `${exports.mergeConflictMarkers.start} ${labelSource}\n`;
-        result += block.source.join('\n') + '\n';
+        if (block.source.length > 0) {
+            result += block.source.join('\n') + '\n';
+        }
         result += `${exports.mergeConflictMarkers.separator}\n`;
-        result += block.incoming.join('\n') + '\n';
+        if (block.incoming.length > 0) {
+            result += block.incoming.join('\n') + '\n';
+        }
         result += `${exports.mergeConflictMarkers.end} ${labelIncoming}\n`;
     }
     return result;

package/dist/utils/path.d.ts

@@ -1,10 +1,10 @@
 import { z } from 'zod';
-export declare const zPosixPath: z.ZodBranded<z.ZodString, "PXL.PosixPath">;
+export declare const zPosixPath: z.core.$ZodBranded<z.ZodString, "PXL.PosixPath", "out">;
 /**
  * A path string that has been normalized to use the unix path separator.
  */
 export type PosixPath = z.infer<typeof zPosixPath>;
-export declare const POSIX_ROOT: string & z.BRAND<"PXL.PosixPath">;
+export declare const POSIX_ROOT: string & z.core.$brand<"PXL.PosixPath">;
 /**
  * Normalizes a unix or Windows path to use the unix path separator. Additionally,
  * it normalizes the path so that every path is considered absolute.

package/dist/utils/string-functions.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
-export declare const zTypescript: z.ZodBranded<z.ZodString, "PXL.Typescript">;
+export declare const zTypescript: z.core.$ZodBranded<z.ZodString, "PXL.Typescript", "out">;
 export type Typescript = z.infer<typeof zTypescript>;
-export declare function ts(input: string): string & z.BRAND<"PXL.Typescript">;
+export declare function ts(input: string): string & z.core.$brand<"PXL.Typescript">;
 export declare function trimLines(input: string): string;
 /**
  * Removes leading and trailing newlines from the input string.

package/dist/utils/sync-log-result.js

@@ -32,10 +32,10 @@ function logSyncResult(results, options = {}) {
             actionGroups['Ejected'].push(path);
         }
     }
+    logActionResult('NoAction', actionGroups['NoAction'], utils_1.cyan, 'unchanged', logger);
+    logActionResult('Write', actionGroups['Write'], utils_1.green, 'written:', logger);
     logActionResult('Delete', actionGroups['Delete'], utils_1.red, 'deleted', logger);
     logActionResult('MergeConflict', actionGroups['MergeConflict'], utils_1.yellow, 'with merge conflicts', logger);
-    logActionResult('Write', actionGroups['Write'], utils_1.green, 'written:', logger);
-    logActionResult('NoAction', actionGroups['NoAction'], utils_1.cyan, 'unchanged', logger);
     if (options.showEjectedStats) {
         if (actionGroups['Ejected'].length === 0) {
             logger.log('✅ No files ejected');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postxl/generator",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Core package that orchestrates the code generation of a PXL project",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -46,8 +46,8 @@
     "jszip": "3.10.1",
     "minimatch": "^10.1.1",
     "p-limit": "3.1.0",
-    "@postxl/schema": "^1.1.1",
-    "@postxl/utils": "^1.1.0"
+    "@postxl/schema": "^1.2.0",
+    "@postxl/utils": "^1.3.0"
   },
   "devDependencies": {
     "@types/diff": "8.0.0"