feat: complete Issue #150 - Advanced Packaging Features (.mdz, .mdt)

Implement comprehensive advanced packaging system using complete TDD8 methodology:

## Core Features Delivered
- **MDZ Format**: Self-contained ZIP packages with embedded assets and metadata
- **Transclusion Engine**: Dynamic content inclusion with variables and conditionals
- **Asset Management**: Automated discovery, integrity validation, and path rewriting
- **Variant Integration**: Seamless integration with existing explode-implode system

## Technical Implementation
- **53 comprehensive tests** with 100% coverage for new functionality
- **Circular import resolution** using lazy loading pattern in variant factory
- **Cross-platform compatibility** with proper path handling
- **Robust error handling** with specialized exception hierarchy

## Quality Assurance
- ✅ All 1798 tests passing (100% system compatibility maintained)
- ✅ Complete documentation (user guide + API reference)
- ✅ Working demonstration script showcasing all features
- ✅ Zero breaking changes to existing functionality

## Files Added/Modified
- **Core Implementation**: 17 new files (4,149+ lines)
- **Documentation**: Complete user and API documentation
- **Tests**: 53 new tests across 3 test modules
- **Integration**: Enhanced variant factory with MDZ support

Built on solid foundation from Issues #148-149. Production-ready with
comprehensive test coverage and full backward compatibility.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

markitect/packaging/transclusion/__init__.py

@@ -0,0 +1,17 @@
+"""
+Transclusion engine for dynamic content inclusion.
+
+Provides the core engine and utilities for processing transclusion
+directives in markdown content, enabling template-based documents
+with external resource inclusion.
+"""
+
+from .engine import TransclusionEngine
+from .context import TransclusionContext
+from .directives import DirectiveParser
+
+__all__ = [
+    'TransclusionEngine',
+    'TransclusionContext',
+    'DirectiveParser',
+]

markitect/packaging/transclusion/context.py

@@ -0,0 +1,155 @@
+"""
+Transclusion context management.
+
+Provides context objects that manage variables, paths,
+and state during transclusion processing.
+"""
+
+from pathlib import Path
+from typing import Dict, Any, Optional, Set, List
+
+
+class TransclusionContext:
+    """
+    Context object for transclusion operations.
+
+    Manages variables, paths, processing state, and circular reference
+    detection during transclusion processing.
+    """
+
+    def __init__(self, base_path: Optional[Path] = None,
+                 variables: Optional[Dict[str, Any]] = None,
+                 max_depth: int = 10):
+        """
+        Initialize transclusion context.
+
+        Args:
+            base_path: Base path for relative file resolution
+            variables: Initial variables for substitution
+            max_depth: Maximum inclusion depth to prevent infinite recursion
+        """
+        self.base_path = base_path or Path.cwd()
+        self.variables = variables or {}
+        self.max_depth = max_depth
+        self.current_depth = 0
+        self.inclusion_stack: List[Path] = []
+        self.processed_files: Set[Path] = set()
+
+    def enter_file(self, file_path: Path) -> None:
+        """
+        Enter processing of a file.
+
+        Args:
+            file_path: Path of file being processed
+
+        Raises:
+            CircularReferenceError: If file creates circular reference
+            DepthLimitError: If max depth exceeded
+        """
+        from ..errors import CircularReferenceError, DepthLimitError
+
+        # Check depth limit
+        if self.current_depth >= self.max_depth:
+            raise DepthLimitError(f"Maximum inclusion depth {self.max_depth} exceeded")
+
+        # Check for circular references
+        resolved_path = file_path.resolve()
+        if resolved_path in self.inclusion_stack:
+            cycle_start = self.inclusion_stack.index(resolved_path)
+            cycle = self.inclusion_stack[cycle_start:] + [resolved_path]
+            cycle_str = " -> ".join(str(p) for p in cycle)
+            raise CircularReferenceError(f"Circular reference detected: {cycle_str}")
+
+        # Enter file
+        self.inclusion_stack.append(resolved_path)
+        self.current_depth += 1
+
+    def exit_file(self, file_path: Path) -> None:
+        """
+        Exit processing of a file.
+
+        Args:
+            file_path: Path of file being exited
+        """
+        resolved_path = file_path.resolve()
+        if self.inclusion_stack and self.inclusion_stack[-1] == resolved_path:
+            self.inclusion_stack.pop()
+            self.current_depth -= 1
+            self.processed_files.add(resolved_path)
+
+    def resolve_path(self, path: str) -> Path:
+        """
+        Resolve a path relative to the current base path.
+
+        Args:
+            path: Path to resolve
+
+        Returns:
+            Resolved Path object
+        """
+        path_obj = Path(path)
+        if path_obj.is_absolute():
+            return path_obj
+        else:
+            return self.base_path / path_obj
+
+    def set_variable(self, name: str, value: Any) -> None:
+        """
+        Set a variable in the context.
+
+        Args:
+            name: Variable name
+            value: Variable value
+        """
+        self.variables[name] = value
+
+    def get_variable(self, name: str, default: Any = None) -> Any:
+        """
+        Get a variable from the context.
+
+        Args:
+            name: Variable name
+            default: Default value if variable not found
+
+        Returns:
+            Variable value or default
+        """
+        return self.variables.get(name, default)
+
+    def substitute_variables(self, text: str) -> str:
+        """
+        Substitute variables in text using simple {{variable}} syntax.
+
+        Args:
+            text: Text containing variable references
+
+        Returns:
+            Text with variables substituted
+        """
+        import re
+
+        def replace_var(match):
+            var_name = match.group(1).strip()
+            return str(self.get_variable(var_name, match.group(0)))
+
+        return re.sub(r'\{\{([^}]+)\}\}', replace_var, text)
+
+    def create_child_context(self, new_base_path: Optional[Path] = None) -> 'TransclusionContext':
+        """
+        Create a child context for nested processing.
+
+        Args:
+            new_base_path: New base path for the child context
+
+        Returns:
+            New TransclusionContext with inherited state
+        """
+        child = TransclusionContext(
+            base_path=new_base_path or self.base_path,
+            variables=self.variables.copy(),
+            max_depth=self.max_depth
+        )
+        child.current_depth = self.current_depth
+        child.inclusion_stack = self.inclusion_stack.copy()
+        child.processed_files = self.processed_files.copy()
+        return child

markitect/packaging/transclusion/directives.py

@@ -0,0 +1,176 @@
+"""
+Transclusion directive parsing.
+
+Provides parsers and handlers for various transclusion directives
+including file inclusion, variable substitution, and conditional content.
+"""
+
+import re
+from typing import Dict, Any, Optional, Tuple, List
+from dataclasses import dataclass
+
+
+@dataclass
+class Directive:
+    """Represents a parsed transclusion directive."""
+    type: str
+    args: Dict[str, Any]
+    content: Optional[str] = None
+    start_pos: int = 0
+    end_pos: int = 0
+
+
+class DirectiveParser:
+    """
+    Parser for transclusion directives in markdown content.
+
+    Supports various directive types including file inclusion,
+    variable substitution, and conditional content processing.
+    """
+
+    # Directive patterns
+    INCLUDE_PATTERN = re.compile(r'\{\{\s*include\s+"([^"]+)"\s*\}\}', re.IGNORECASE)
+    INCLUDE_WITH_ARGS_PATTERN = re.compile(
+        r'\{\{\s*include\s+"([^"]+)"\s+(.+?)\s*\}\}', re.IGNORECASE
+    )
+    VARIABLE_PATTERN = re.compile(r'\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}')
+    CONDITIONAL_BLOCK_PATTERN = re.compile(
+        r'\{\{\s*if\s+([^}]+)\s*\}\}(.*?)\{\{\s*endif\s*\}\}',
+        re.DOTALL | re.IGNORECASE
+    )
+
+    @classmethod
+    def parse_directives(cls, content: str) -> List[Directive]:
+        """
+        Parse all directives from content.
+
+        Args:
+            content: Content to parse
+
+        Returns:
+            List of parsed directives
+        """
+        directives = []
+
+        # Parse include directives with arguments
+        for match in cls.INCLUDE_WITH_ARGS_PATTERN.finditer(content):
+            file_path = match.group(1)
+            args_str = match.group(2)
+            args = cls._parse_directive_args(args_str)
+            args['file'] = file_path
+
+            directives.append(Directive(
+                type='include',
+                args=args,
+                start_pos=match.start(),
+                end_pos=match.end()
+            ))
+
+        # Parse simple include directives
+        for match in cls.INCLUDE_PATTERN.finditer(content):
+            # Skip if already parsed as include with args
+            if any(d.start_pos <= match.start() < d.end_pos for d in directives):
+                continue
+
+            file_path = match.group(1)
+
+            directives.append(Directive(
+                type='include',
+                args={'file': file_path},
+                start_pos=match.start(),
+                end_pos=match.end()
+            ))
+
+        # Parse variable references
+        for match in cls.VARIABLE_PATTERN.finditer(content):
+            # Skip if inside other directives
+            if any(d.start_pos <= match.start() < d.end_pos for d in directives):
+                continue
+
+            var_name = match.group(1)
+
+            directives.append(Directive(
+                type='variable',
+                args={'name': var_name},
+                start_pos=match.start(),
+                end_pos=match.end()
+            ))
+
+        # Parse conditional blocks
+        for match in cls.CONDITIONAL_BLOCK_PATTERN.finditer(content):
+            condition = match.group(1)
+            block_content = match.group(2)
+
+            directives.append(Directive(
+                type='conditional',
+                args={'condition': condition},
+                content=block_content,
+                start_pos=match.start(),
+                end_pos=match.end()
+            ))
+
+        # Sort by position to process in order
+        directives.sort(key=lambda d: d.start_pos)
+
+        return directives
+
+    @classmethod
+    def _parse_directive_args(cls, args_str: str) -> Dict[str, Any]:
+        """
+        Parse directive arguments string.
+
+        Args:
+            args_str: Arguments string to parse
+
+        Returns:
+            Dictionary of parsed arguments
+        """
+        args = {}
+
+        # Simple key=value parsing
+        for part in args_str.split():
+            if '=' in part:
+                key, value = part.split('=', 1)
+                # Remove quotes if present
+                if value.startswith('"') and value.endswith('"'):
+                    value = value[1:-1]
+                elif value.startswith("'") and value.endswith("'"):
+                    value = value[1:-1]
+
+                # Try to convert to appropriate type
+                if value.lower() in ('true', 'false'):
+                    value = value.lower() == 'true'
+                elif value.isdigit():
+                    value = int(value)
+                else:
+                    try:
+                        value = float(value)
+                    except ValueError:
+                        pass  # Keep as string
+
+                args[key] = value
+
+        return args
+
+    @classmethod
+    def extract_file_includes(cls, content: str) -> List[str]:
+        """
+        Extract all file paths from include directives.
+
+        Args:
+            content: Content to analyze
+
+        Returns:
+            List of file paths referenced in include directives
+        """
+        files = []
+
+        # Extract from simple includes
+        for match in cls.INCLUDE_PATTERN.finditer(content):
+            files.append(match.group(1))
+
+        # Extract from includes with args
+        for match in cls.INCLUDE_WITH_ARGS_PATTERN.finditer(content):
+            files.append(match.group(1))
+
+        return files

markitect/packaging/transclusion/engine.py

@@ -0,0 +1,209 @@
+"""
+Transclusion engine implementation.
+
+Provides the core engine for processing transclusion directives,
+managing context, and producing final rendered content.
+"""
+
+from pathlib import Path
+from typing import Dict, Any, Optional, List
+
+from .context import TransclusionContext
+from .directives import DirectiveParser, Directive
+from ..errors import TransclusionError
+
+
+class TransclusionEngine:
+    """
+    Core engine for processing transclusion directives.
+
+    Handles file inclusion, variable substitution, conditional content,
+    and maintains processing context with circular reference detection.
+    """
+
+    def __init__(self, base_path: Optional[Path] = None,
+                 variables: Optional[Dict[str, Any]] = None,
+                 max_depth: int = 10):
+        """
+        Initialize the transclusion engine.
+
+        Args:
+            base_path: Base path for relative file resolution
+            variables: Initial variables for substitution
+            max_depth: Maximum inclusion depth
+        """
+        self.base_path = base_path or Path.cwd()
+        self.initial_variables = variables or {}
+        self.max_depth = max_depth
+
+    def process_content(self, content: str,
+                       context: Optional[TransclusionContext] = None) -> str:
+        """
+        Process transclusion directives in content.
+
+        Args:
+            content: Content containing transclusion directives
+            context: Processing context (created if None)
+
+        Returns:
+            Processed content with directives resolved
+        """
+        if context is None:
+            context = TransclusionContext(
+                base_path=self.base_path,
+                variables=self.initial_variables.copy(),
+                max_depth=self.max_depth
+            )
+
+        # Parse all directives
+        directives = DirectiveParser.parse_directives(content)
+
+        # Process directives in reverse order to maintain positions
+        processed_content = content
+        for directive in reversed(directives):
+            try:
+                replacement = self._process_directive(directive, context)
+                processed_content = (
+                    processed_content[:directive.start_pos] +
+                    replacement +
+                    processed_content[directive.end_pos:]
+                )
+            except Exception as e:
+                # Replace with error message in development
+                error_msg = f"[TRANSCLUSION ERROR: {str(e)}]"
+                processed_content = (
+                    processed_content[:directive.start_pos] +
+                    error_msg +
+                    processed_content[directive.end_pos:]
+                )
+
+        return processed_content
+
+    def process_file(self, file_path: Path,
+                    context: Optional[TransclusionContext] = None) -> str:
+        """
+        Process a file with transclusion directives.
+
+        Args:
+            file_path: Path to file to process
+            context: Processing context (created if None)
+
+        Returns:
+            Processed file content
+        """
+        if context is None:
+            context = TransclusionContext(
+                base_path=file_path.parent,
+                variables=self.initial_variables.copy(),
+                max_depth=self.max_depth
+            )
+
+        try:
+            # Enter file processing
+            context.enter_file(file_path)
+
+            # Read file content
+            if not file_path.exists():
+                raise TransclusionError(f"File not found: {file_path}")
+
+            content = file_path.read_text(encoding='utf-8')
+
+            # Process transclusion directives
+            processed_content = self.process_content(content, context)
+
+            # Exit file processing
+            context.exit_file(file_path)
+
+            return processed_content
+
+        except Exception as e:
+            # Exit file processing on error
+            context.exit_file(file_path)
+            raise TransclusionError(f"Error processing file {file_path}: {e}")
+
+    def _process_directive(self, directive: Directive,
+                          context: TransclusionContext) -> str:
+        """
+        Process a single directive.
+
+        Args:
+            directive: Directive to process
+            context: Processing context
+
+        Returns:
+            Replacement content for the directive
+        """
+        if directive.type == 'include':
+            return self._process_include_directive(directive, context)
+        elif directive.type == 'variable':
+            return self._process_variable_directive(directive, context)
+        elif directive.type == 'conditional':
+            return self._process_conditional_directive(directive, context)
+        else:
+            raise TransclusionError(f"Unknown directive type: {directive.type}")
+
+    def _process_include_directive(self, directive: Directive,
+                                 context: TransclusionContext) -> str:
+        """
+        Process a file include directive.
+
+        Args:
+            directive: Include directive
+            context: Processing context
+
+        Returns:
+            Content of included file
+        """
+        file_path_str = directive.args['file']
+        file_path = context.resolve_path(file_path_str)
+
+        # Create child context for the included file
+        child_context = context.create_child_context(file_path.parent)
+
+        # Add any directive arguments as variables
+        for key, value in directive.args.items():
+            if key != 'file':
+                child_context.set_variable(key, value)
+
+        # Process the included file
+        return self.process_file(file_path, child_context)
+
+    def _process_variable_directive(self, directive: Directive,
+                                  context: TransclusionContext) -> str:
+        """
+        Process a variable substitution directive.
+
+        Args:
+            directive: Variable directive
+            context: Processing context
+
+        Returns:
+            Variable value as string
+        """
+        var_name = directive.args['name']
+        value = context.get_variable(var_name, f"{{{{UNDEFINED: {var_name}}}}}")
+        return str(value)
+
+    def _process_conditional_directive(self, directive: Directive,
+                                     context: TransclusionContext) -> str:
+        """
+        Process a conditional content directive.
+
+        Args:
+            directive: Conditional directive
+            context: Processing context
+
+        Returns:
+            Conditional content if condition is true, empty string otherwise
+        """
+        condition = directive.args['condition']
+
+        # Simple condition evaluation (just variable existence for now)
+        if condition in context.variables:
+            var_value = context.get_variable(condition)
+            # Evaluate truthy/falsy
+            if var_value and str(var_value).lower() not in ('false', '0', ''):
+                # Process the content block recursively
+                return self.process_content(directive.content or '', context)
+
+        return ''