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).