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.

## Table of Contents
- [Phase 1: Core Architecture & Environment](#phase-1-core-architecture--environment)
- [Phase 2: Lexical Analysis & Tokenization](#phase-2-lexical-analysis--tokenization)
- [Phase 3: The AST & Parser](#phase-3-the-ast--parser)
- [Phase 4: The Interpreter (Rendering Engine)](#phase-4-the-interpreter-rendering-engine)
- [Phase 5: Inheritance & Reusability](#phase-5-inheritance--reusability)
- [Phase 6: Extensibility & Performance](#phase-6-extensibility--performance)
- [Phase 7: Final Polish & Release](#phase-7-final-polish--release)

## Phase 1: Core Architecture & Environment
*Focus: Establishing the contracts, error handling, and runtime configuration.*
- [x] Define and implement `Scape\Interfaces\FilterInterface` and `Scape\Interfaces\HostProviderInterface`.
- [x] Implement the Exception hierarchy in `Scape\Exceptions`.
- [x] Implement `Scape\Config` to handle environment variables (`SCAPE_*_DIR`) and programmatic overrides.
- [x] 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.*
- [x] Implement `Scape\Parser\Lexer` to identify interpolation `{{ }}`, raw `{{{ }}}`, logic `{( )}`, and block `{[ ]}` tags.
- [x] Support white-space independence within tags.
- [x] Implement the white-space control rule (logic tags consuming one trailing newline).
- [x] Comprehensive unit tests for all tag variations.

## Phase 3: The AST & Parser
*Focus: Building the Abstract Syntax Tree (AST) representing the template's structure.*
- [x] Implement `Scape\Parser\Parser` to convert tokens into an AST.
- [x] Define AST Nodes (Text, Variable, Loop, Block, Include, Filter).
- [x] Implement the `foreach` grammar (with optional keys).
- [x] 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.*
- [x] Implement the AST Interpreter to walk the tree and resolve variables.
- [x] Implement standard HTML escaping (`ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML5`).
- [x] Implement Loop logic with `index`, `pos`, and positional rendering (`first`, `inner`, `last`).
- [x] Implement `debug` vs `production` variable access modes.

## Phase 5: Inheritance & Reusability
*Focus: Blocks, Layouts, and Partials.*
- [x] Implement `{[ extends ]}` and the Block override system (including `{[ parent ]}`).
- [x] Implement `{[ include ]}` with data scoping rules (`with context`, `with data_source`, inline arrays).
- [x] Implement the recursion limit check (default 20).
- [x] Implement the 404 fallback mechanism.

## Phase 6: Extensibility & Performance
*Focus: Filters, Host IoC, and Caching.*
- [x] Implement the Filter pipeline (piping and arguments).
- [x] Implement `uses` and `load_filter` mechanisms.
- [x] Implement the `host` namespace delegation.
- [x] Implement AST Caching (local storage in `.scape/cache`) with `mtime` invalidation for dev mode.

## Phase 7: Final Polish & Release
- [x] Final project-wide code style audit.
- [x] Ensure 100% test coverage for core rendering logic.
- [x] Draft the final README (Getting Started and examples).