Refactor page-compiler format API to modular transforms pipeline

[YusukeHirao]

Summary

Complete refactoring of page-compiler's format API into a modular transforms pipeline with improved extensibility and v1.3.0 compatibility fixes.

Breaking Changes

1. Unified transforms option replaces individual format options (prettier, minifier, imageSizes, etc.)
2. API renames: formatHtml → pageTransform, FormatHtmlOptions → integrated into PageCompilerOptions
3. Unified Transform interface across page-compiler and devServer
4. Package exports restructured: ./format → ./page-transform + individual transform exports

New Features

• Function support for transforms - extend defaults without explicit imports
• Modular transform factories - manipulateDOM, characterEntities, doctype, prettier, minifier, lineBreak
• Enhanced TransformContext - added filePath, outputDir, compile function

Bug Fixes & Compatibility

• Fix imageSizes not working with custom hooks (now receives parent elements, not img elements)
• Fix fragment handling (fragments stay as fragments, not wrapped in full HTML)
• Remove characterEntities from defaults (opt-in only, matching v1.3.0)
• imageSizes defaults to true (matching v1.3.0)
• Remove direct jsdom dependency (use kamado's domSerialize)

Files Changed

New Files

• src/page-transform.ts - defaultPageTransforms export
• src/page-transform.spec.ts - Transform pipeline tests
• src/transform/manipulate-dom.ts - DOM manipulation transform (with imageSizes)
• src/transform/character-entities.ts - Character entity conversion
• src/transform/doctype.ts - DOCTYPE declaration
• src/transform/prettier.ts - HTML formatting
• src/transform/minifier.ts - HTML minification
• src/transform/line-break.ts - Line break normalization
• Comprehensive test files for each transform

Removed Files

• src/format.ts - replaced by modular transforms
• src/format.spec.ts - replaced by transform-specific tests

Modified Files

• src/page-compiler.ts - Use transforms pipeline instead of formatHtml
• src/types.ts - Replace format options with transforms option
• package.json - Update exports, remove jsdom dependencies
• README.md - Complete documentation rewrite
• src/transform/inject-to-head.ts - Updated to Transform interface
• src/transform/ssi-shim.ts - Updated to Transform interface
• kamado/src/config/types.ts - Unified Transform interface

Migration Guide

Before (v1.x)

import { pageCompiler } from '@kamado-io/page-compiler';

pageCompiler({
  layouts: { dir: './layouts' },
  imageSizes: true,
  prettier: { printWidth: 120 },
  minifier: { collapseWhitespace: true },
  characterEntities: true,
});

After (v2.x)

import { pageCompiler, characterEntities } from '@kamado-io/page-compiler';

// Option 1: Use defaults (imageSizes true, no characterEntities)
pageCompiler({
  layouts: { dir: './layouts' },
});

// Option 2: Customize with function (no imports needed)
pageCompiler({
  layouts: { dir: './layouts' },
  transforms: (defaults) => [
    ...defaults.map(t => 
      t.name === 'prettier' 
        ? prettier({ options: { printWidth: 120 } })
        : t
    ),
    characterEntities(), // Opt-in
  ],
});

// Option 3: Full custom selection
import { manipulateDOM, prettier, minifier } from '@kamado-io/page-compiler';

pageCompiler({
  layouts: { dir: './layouts' },
  transforms: [
    manipulateDOM({ 
      imageSizes: true,
      hook: async (elements, window, ctx) => {
        // Custom DOM manipulation
      }
    }),
    prettier({ options: { printWidth: 120 } }),
    minifier({ options: { collapseWhitespace: true } }),
  ],
});

API Changes

defaultPageTransforms

// v2.x default pipeline (5 transforms)
[
  manipulateDOM({ imageSizes: true }),
  doctype(),
  prettier(),
  minifier(),
  lineBreak(),
]

Transform Interface

interface Transform {
  name: string;
  transform: (
    content: string | ArrayBuffer,
    context: TransformContext
  ) => string | ArrayBuffer | Promise<string | ArrayBuffer>;
  filter?: TransformFilter; // Only for devServer.transforms
}

Package Exports

// Main
import { pageCompiler, defaultPageTransforms } from '@kamado-io/page-compiler';

// Transforms
import { manipulateDOM } from '@kamado-io/page-compiler/transform/manipulate-dom';
import { characterEntities } from '@kamado-io/page-compiler/transform/character-entities';
import { doctype } from '@kamado-io/page-compiler/transform/doctype';
import { prettier } from '@kamado-io/page-compiler/transform/prettier';
import { minifier } from '@kamado-io/page-compiler/transform/minifier';
import { lineBreak } from '@kamado-io/page-compiler/transform/line-break';

// Page transform module
import { defaultPageTransforms } from '@kamado-io/page-compiler/page-transform';

Test Coverage

• ✅ All transform modules have comprehensive tests
• ✅ Transform pipeline tests (page-transform.spec.ts)
• ✅ Integration tests (page-compiler.spec.ts)
• ✅ Fragment preservation tests
• ✅ Function-based transforms extension tests

🤖 Generated with Claude Code