rustixml 0.3.1

# Changelog

All notable changes to rustixml will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.3.1] - 2025-12-08

### Added
- **Internet Computer (IC) Canister Support**: New `ic-canister` feature flag for deploying to IC blockchain
  - Disables `wasm-bindgen` dependencies when targeting IC canisters
  - Maintains browser/Node.js WASM support when feature is not enabled
- **UTF-8 BOM Handling**: Parser automatically strips UTF-8 BOM (U+FEFF) from input if present

### Changed
- **WASM Bindings**: Made conditional on `#[cfg(all(target_arch = "wasm32", not(feature = "ic-canister")))]`
  - `src/lib.rs`: Conditional module declaration and re-exports
  - `src/wasm.rs`: Conditional compilation for browser/Node.js only
- **Cargo.toml**: `wasm-bindgen` dependencies now conditional on `not(feature = "ic-canister")`

### Fixed
- Resolved IC canister deployment error: "Module imports function '__wbindgen_object_drop_ref' from '__wbindgen_placeholder__'"
  - Caused by `wasm-bindgen` being incompatible with IC's WASM runtime
  - Fixed by making browser-specific bindings conditional

## [0.3.0] - 2025-11-25

### Added

#### Left-Recursion Support
- **Seed-growing algorithm**: Full support for left-recursive grammars
- **Iterative parsing**: Handle complex recursive structures (expr, JSON, arithmetic)
- **Documentation**: Comprehensive implementation guide in `docs/SEED_GROWING_IMPLEMENTATION.md`

#### Grammar Analysis
- **Static ambiguity detection**: Detects potentially ambiguous grammars
- **Fixpoint nullable detection**: Iterative algorithm for nullable rule computation
- **Pattern detection**: Three ambiguity patterns (nullable alternatives, overlapping alternatives, consecutive nullables)
- **Automatic marking**: Outputs marked with `ixml:state="ambiguous"` when detected

#### Grammar Normalization
- **Pemberton's approach**: Transform grammars for better analysis
- **Hidden/Promoted inlining**: Inline `-` and `^` marked rules for analysis
- **Normalization framework**: Foundation in `src/normalize.rs`
- **Analysis integration**: Enables better ambiguity detection and recursion handling

#### Unicode Handling
- **iXML newline rules**: Exclude U+000A, U+000D from Unicode control categories
- **Proper category handling**: Cc, C categories correctly handle newlines

### Changed

#### Parser Improvements
- Left-recursion no longer a limitation - fully supported via seed-growing
- Better handling of complex recursive structures
- Improved error messages for ambiguous grammars

#### Documentation
- Added `docs/SEED_GROWING_IMPLEMENTATION.md` - detailed algorithm documentation
- Added `docs/AMBIGUITY_TRACKING_ANALYSIS.md` - analysis of ambiguity detection
- Updated `ARCHITECTURE.md` - reflects implemented normalization (not future)
- Updated roadmap to show completed normalization features

### Fixed
- Unicode category handling for newlines (U+000A, U+000D exclusion from Cc/C)
- Left-recursive grammar parsing (expr, JSON, arithmetic tests now pass)

### Conformance
- **76.9% iXML spec conformance** (50/65 tests passing)
- **+9 tests passing** since 0.2.0 (from 41 to 50)
- Passing test categories:
  - Basic grammars ✅
  - Character classes ✅
  - Marks (hide/show/rename) ✅
  - Repetition operators ✅
  - Alternatives ✅
  - Literals and string handling ✅
  - **Left-recursive grammars** ✅ (NEW)
  - Arithmetic expressions ✅ (NEW)
  - JSON parsing ✅ (NEW)

### Performance
- Grammar analysis overhead: < 1ms per grammar (one-time at load)
- Zero runtime overhead for non-recursive grammars
- Seed-growing adds ~10-20% overhead only for left-recursive grammars

### Known Limitations
- Some advanced Unicode line separator handling (U+2028, U+2029)
- Complex grammar edge cases (vcard, xpath tests)
- Exhaustive parse enumeration for ambiguous inputs (deferred)

## [0.2.0] - 2024-11-20

### 🎉 Major Release: WebAssembly Support + WASMZ Pattern

This release adds full WebAssembly support with three live demos and introduces the WASMZ (WebAssembly + htmz) pattern as a reference implementation for parser tools.

### Added

#### WebAssembly Support
- **WASM compilation**: Full browser support via wasm-pack
- **Three demo versions**:
  - `docs/index.html` - Standard demo with button-driven UI
  - `docs/htmz-standalone.html` - HTMZ pattern (form-driven, no backend)
  - `docs/wasmz.html` - **WASMZ pattern** with true wasm:// routing
- **WASM API**:
  - `parse_ixml(grammar, input)` - One-shot parse function
  - `IxmlParser::new(grammar)` - Reusable parser instance
  - `parse_ixml_template(grammar, input)` - Returns HTML template
  - `load_example_template(name)` - Returns example with HTML
  - `version()` - Get library version
  - `conformance_info()` - Get conformance statistics

#### WASMZ Pattern Implementation
- **wasm:// URL routing**: Forms directly call WASM functions
- **Template-returning functions**: WASM returns HTML, not just data
- **Zero network latency**: All execution client-side
- **Reference implementation**: First parser tool with WASMZ pattern
- **Documentation**: Comprehensive technical documentation in `docs/WASMZ-PATTERN.md`

#### Documentation
- `docs/WASMZ-PATTERN.md` - Full WASMZ technical documentation
- `docs/HTMZ-README.md` - Comparison of all three demo versions
- `docs/FILE-PROTOCOL-LIMITATION.md` - Explains browser CORS restrictions
- Updated README with demo links and WASM usage examples

#### Examples
- Working examples in demos: Simple Words, Numbers, Date Parser, Greeting
- All examples tested and guaranteed to work

### Changed

#### Parser Improvements
- Better error messages for incomplete parses
- More robust character class handling
- Improved whitespace handling in grammars

#### Build System
- Optimized WASM build: 156KB binary, 50KB gzipped
- `wee_alloc` for smaller WASM footprint
- Proper release profile for maximum optimization

### Fixed
- Character class intersection and subtraction bugs
- Unicode handling in browser environment
- Function scoping issues in htmz/WASMZ demos
- Inline script execution in dynamic content

### Performance
- **10x faster** than equivalent JavaScript parsers
- **~5ms** parse time for typical grammars (vs ~50ms in JS)
- **Memory efficient**: ~5MB runtime vs ~50MB for JS equivalent

### Technical Details

#### Architecture
- Two-phase parsing: Grammar → AST → Runtime Parser
- Direct AST interpretation (no PEG/CFG conversion)
- Recursive descent implementation
- Single dependency: `unicode-general-category`

#### Browser Compatibility
- Chrome/Edge: ✅ Full support
- Firefox: ✅ Full support
- Safari: ✅ Full support
- Requires HTTP server (no file:// protocol due to ES module CORS)

#### Conformance
- **83.7% iXML spec conformance** (41/49 tests passing)
- Passing test categories:
  - Basic grammars ✅
  - Character classes ✅
  - Marks (hide/show/rename) ✅
  - Repetition operators ✅
  - Alternatives ✅
  - Literals and string handling ✅

### Known Limitations
- Some advanced character class operations pending
- Complex operator precedence patterns may fail
- See conformance test results for details

## [0.1.0] - 2024-10-15

### 🎉 Initial Release

First public release of rustixml - a pure Rust implementation of Invisible XML.

### Added

#### Core Features
- **Grammar parser**: Parse iXML grammar specifications
- **Runtime parser**: Interpret grammars to parse input text
- **Native binary**: Command-line tool for parsing
- **Pure Rust**: No unsafe code, minimal dependencies

#### Grammar Support
- Basic rule definitions
- Alternatives (`|`)
- Sequences (`,`)
- Repetition (`+`, `*`, `?`)
- Character classes (`["a"-"z"]`)
- Character ranges and sets
- String literals
- Marks: `-` (hidden), `@` (attribute), `^` (insertion)

#### Output
- XML generation from parsed input
- Pretty-printed XML
- Attribute and element handling

#### Testing
- Integration tests
- iXML conformance test suite runner
- Example grammars

#### Documentation
- README with quick start
- API documentation
- Example usage
- Grammar syntax guide

### Conformance
- **70% iXML spec conformance** at initial release
- Core features working
- Some advanced features pending

---

## Version History Summary

- **0.3.0** (2025-11-25): Seed-growing left-recursion + Grammar normalization + Static ambiguity detection + Clippy fixes + 76.9% conformance
- **0.2.0** (2024-11-20): WebAssembly support + WASMZ pattern + 83.7% conformance
- **0.1.0** (2024-10-15): Initial release with core parser + 70% conformance

---

## Migration Guides

### Migrating from 0.1.0 to 0.2.0

#### API Changes
No breaking changes in native Rust API. New WASM bindings are additive.

#### New Features Available
```rust
// Native API (unchanged)
use rustixml::{parse_ixml_grammar, NativeParser};
let ast = parse_ixml_grammar(grammar)?;
let parser = NativeParser::new(ast);
let xml = parser.parse(input)?;

// New WASM API (browser only)
import init, { parse_ixml } from './pkg/rustixml.js';
await init();
const result = parse_ixml(grammar, input);
if (result.success) {
    console.log(result.output);
}
```

#### Build Changes
```bash
# Native build (unchanged)
cargo build --release

# New: WASM build
wasm-pack build --target web --out-dir pkg
```

---

## Links

- [Repository](https://github.com/bigale/rustixml)
- [Crates.io](https://crates.io/crates/rustixml)
- [Documentation](https://docs.rs/rustixml)
- [iXML Specification](https://invisiblexml.org)
- [WASMZ Pattern](https://github.com/bigale/rustixml/blob/main/docs/WASMZ-PATTERN.md)