Scape/MILESTONES.md

Scape Templates — Project Milestones

This document outlines the phased roadmap for building Scape Templates. Each milestone is designed to ensure "Excellence over Features," focusing on a solid foundation before adding complexity.

Phase 1: Core Architecture & Environment

Focus: Establishing the contracts, error handling, and runtime configuration.

• Define and implement Scape\Interfaces\FilterInterface and Scape\Interfaces\HostProviderInterface.
• Implement the Exception hierarchy in Scape\Exceptions.
• Implement Scape\Config to handle environment variables (SCAPE_*_DIR) and programmatic overrides.
• Create the Scape\Engine boilerplate with the render() method signature.

Phase 2: Lexical Analysis & Tokenization

Focus: Turning template strings into a stream of tokens that the parser can understand.

• Implement Scape\Parser\Lexer to identify interpolation {{ }}, raw {{{ }}}, logic {( )}, and block {[ ]} tags.
• Support white-space independence within tags.
• Implement the white-space control rule (logic tags consuming one trailing newline).
• Comprehensive unit tests for all tag variations.

Phase 3: The AST & Parser

Focus: Building the Abstract Syntax Tree (AST) representing the template's structure.

• Implement Scape\Parser\Parser to convert tokens into an AST.
• Define AST Nodes (Text, Variable, Loop, Block, Include, Filter).
• Implement the foreach grammar (with optional keys).
• Implement data access logic (dot-notation for objects, brackets for arrays).

Phase 4: The Interpreter (Rendering Engine)

Focus: Turning the AST and data into the final HTML output.

• Implement the AST Interpreter to walk the tree and resolve variables.
• Implement standard HTML escaping (ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML5).
• Implement Loop logic with index, pos, and positional rendering (first, inner, last).
• Implement debug vs production variable access modes.

Phase 5: Inheritance & Reusability

Focus: Blocks, Layouts, and Partials.

• Implement {[ extends ]} and the Block override system (including {[ parent ]}).
• Implement {[ include ]} with data scoping rules (with context, with data_source, inline arrays).
• Implement the recursion limit check (default 20).
• Implement the 404 fallback mechanism.

Phase 6: Extensibility & Performance

Focus: Filters, Host IoC, and Caching.

• Implement the Filter pipeline (piping and arguments).
• Implement uses and load_filter mechanisms.
• Implement the host namespace delegation.
• Implement AST Caching (local storage in .scape/cache) with mtime invalidation for dev mode.

Phase 7: Final Polish & Release

• Final project-wide code style audit.
• Ensure 100% test coverage for core rendering logic.
• Draft the final README (Getting Started and examples).