feat(page-compiler): improve Transform API for dual-mode usage

[YusukeHirao]

Summary

Improves the Transform API to support both development and build modes by adding TransformContext to compiler hooks and renaming the directory structure to reflect dual-mode capabilities.

Key Changes

1. Directory Rename

• Renamed dev-transform/ → transform/ to reflect dual-mode usage
• Maintained backward compatibility in package.json exports
• Updated all documentation references

2. TransformContext Integration

• Added TransformContext as 3rd parameter to beforeSerialize hook
• Added TransformContext as 4th parameter to afterSerialize hook
• Provides access to path, inputPath, outputPath, isServe, and full context

3. Dual-Mode Support

• Transform utilities (injectToHead, createSSIShim) can now be used in both dev and build contexts
• devServer.transforms continues to apply only in serve mode (unchanged)
• Users can manually call transform utilities in beforeSerialize for build-time transformations

4. Comprehensive Documentation

• Added dedicated TransformContext section explaining all properties
• Added advanced usage examples (conditional processing, file operations)
• Clarified that devServer.transforms is serve-mode only
• Updated all signatures in Options sections
• Updated ARCHITECTURE.md to reflect current implementation

Test Coverage

• Added 6 new tests for TransformContext in hooks
• All 156 tests passing
• Build verification successful

Breaking Changes

⚠️ beforeSerialize and afterSerialize signatures have changed:

Before:

beforeSerialize?: (content: string, isServe: boolean) => Promise<string> | string
afterSerialize?: (elements: readonly Element[], window: Window, isServe: boolean) => Promise<void> | void

After:

beforeSerialize?: (content: string, isServe: boolean, context: TransformContext) => Promise<string> | string
afterSerialize?: (elements: readonly Element[], window: Window, isServe: boolean, context: TransformContext) => Promise<void> | void

Existing code that doesn't use the new parameter will continue to work (JavaScript ignores extra parameters).

Migration Guide

Using Transform Utilities in Build Time

import { createInjectToHeadTransform } from '@kamado-io/page-compiler/transform/inject-to-head';

const pageCompilerOptions: PageCompilerOptions = {
    beforeSerialize: async (content, isServe, context) => {
        const injectTransform = createInjectToHeadTransform({
            content: '<meta name="generator" content="Kamado">',
        });
        return await injectTransform(content, context);
    },
};

Conditional Processing Based on Path

beforeSerialize: async (content, isServe, context) => {
    if (context.path.startsWith('admin/')) {
        // Special processing for admin pages
    }
    return content;
};

🤖 Generated with Claude Code

[cursor]

You have run out of free Bugbot PR reviews for this billing cycle. This will reset on February 26.

To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.