V2 Roadmap

[multiarc]

Heddle v2.0

The 2.0 evolution: a sandbox-safe expression tier, safe-by-default output, declarative branching, a component model, editor tooling, a build-time compiler, and a streaming render surface. Almost everything is additive and differential-gated — the dynamic engine's rendered bytes are unchanged. The breaking changes are two engine defaults flipped together and the removal of the legacy @import() include (see Migration).

Native expression tier

A sandbox-safe, Roslyn-free expression language in call parens: @if(Count > 0), @(Price * Quantity), @(Name ?? "anon"), @(IsFeatured ? "★" : ""). Operators and literals follow the C# precedence table exactly and compile to System.Linq.Expressions delegates — no Roslyn, no arbitrary method calls. Capability is limited to properties/indexers/operators/literals plus host-registered whitelisted functions (FunctionRegistry, [ExportFunctions]). ExpressionMode selects MemberPathsOnly / Native (default) / FullCSharp; the inner-@ form stays full C#.

Safe output by default

An OutputProfile.Html profile HTML-encodes the unnamed @(...) carrier, closing the XSS-by-default gap, with @raw(...) as the explicit opt-out and a @profile(html|text) directive that flips mid-document. The HTML encoder is a pluggable TemplateOptions.Encoder (System.Text.Encodings.Web.TextEncoder) — opt-in, with the default preserving the existing WebUtility.HtmlEncode bytes — and context-encoding extensions @attr / @js / @url cover the HTML-attribute, JavaScript-string-literal, and URL-component contexts that element-text encoding does not.

Declarative branching

Optional @elif/@else as ordinary extensions that coordinate with a preceding @if/@ifnot through a published local context — no new keywords, no chaining, no imperative statement structure. Text between branch blocks is stripped with a warning (industry-standard adjacency). The underlying publish/read channel (Scope.Publish/TryRead, BranchState) is public API for custom extensions to coordinate; branch-set classification is driven by [BranchRole], so a custom extension can join or form a set with the same semantics as the built-ins.

Ergonomics

@for(5) / @for(Count) / @for(range(...)) loop sugar (no more hand-written C# loop models), an opt-in TrimDirectiveLines that swallows whole-line directives' trailing newlines, and a double-render warning when a default-output definition is also called by name.

Named props & slots

Definitions gain typed named parameters with defaults (@card(Article, style: "wide", compact: true)), prop reads in bodies, and parameterized @out() slots — with abstract-definition composition and inheritance narrowing. Missing/unknown/mistyped props are positioned compile errors at the call site.

Editor tooling & LSP

Editor tooling extracted as a zero-breaking-change, flag-gated projection (Heddle.LanguageServices, null-cost when off) plus a hand-rolled LSP 3.17 server: typed member completion inside @(...), hover types, diagnostics at template positions, and go-to-definition across @<< imports (imported-file diagnostics re-anchored to the import site). Ships with a VS Code extension.

Build-time precompilation

A Roslyn incremental source generator (Heddle.Generator) compiles .heddle templates to IProcessStrategy classes at build time — Razor-style, byte-for-byte identical to the dynamic engine, with no runtime Heddle dependency in the generated output. Covers the full construct set (member paths, native expressions, verbatim C#, :: dynamic, branches, @list/@for, definitions/props/slots, @partial, @profile, [ExportFunctions], @<< composition imports); template errors become positioned build diagnostics (HED70xx) and anything not yet emittable degrades safely to the dynamic path (e.g. the step-back value-call encoders @attr/@js/@url render dynamically, byte-identically). A whole-corpus differential gate proves parity. The runtime stays fully dynamic; a Heddle.CSharpTierEnabled trim switch keeps Roslyn out of a trimmed publish. Ships with the heddle CLI (heddle render <template> --model-json <file>), a T4-successor render tool.

Streaming & UTF-8 render surface

New Generate(data, TextWriter) and Generate(data, IBufferWriter<byte>) sink overloads with a two-tier, surrogate-safe UTF-8 transcode path — render straight into Response.BodyWriter with no full-string materialization. The string path stays bit-identical; sink paths allocate O(1) regardless of output size (benchmarked). Precompiled templates emit the sink entry points too, with an opt-in "…"u8 static-piece fast path.

Render budgets

Optional TemplateOptions.RenderBudget sets per-render resource caps for running untrusted templates — MaxOutputChars, MaxRenderOps, and MaxRenderTime — and a breach throws TemplateRenderBudgetException carrying Kind/Limit/Observed. Default is unlimited with zero render-path cost; enforcement lives at the renderer seam, so counts are uniform across the string/TextWriter/IBufferWriter sinks and identical on the dynamic and precompiled backends.

Demo, samples & docs

A progressively-enhanced in-browser demo (Ace editor + typed WASM language worker + sandboxed render pane) on the published docs site, backed by a trimmed Roslyn-pure WebAssembly host and a Playwright smoke suite. A gallery of ten runnable, golden-asserted samples (SSR, streaming SSR, sandboxed templates, HTML-safe output, component props/slots, custom extensions, definition libraries, dynamic models, build-time codegen, precompiled apps) doubling as end-to-end CI coverage, plus a traceability artifact mapping success criteria to the tests that prove them.

Migration (2.0 breaking changes)

Coming from 1.x, three changes need attention, absorbed as one migration:

• Output profile default Text → Html — the unnamed @(...) now HTML-encodes. Opt out per output with @raw, or restore per template with OutputProfile.Text.
• TrimDirectiveLines default-on — whole-line directives swallow their trailing newline. Set TrimDirectiveLines = false to restore 1.x behavior.
• Legacy @import() removed — any @import call site now fails to compile with a positioned HED4003 error; use @<<{{ path }} to share definitions/layouts, or @partial(){{ name }} to embed another template's rendered output inline.

Everything else is additive — including the pluggable Encoder (default preserves existing bytes), the @attr/@js/@url context-encoders, and render budgets. TemplateOptions.AllowCSharp is deprecated in favour of ExpressionMode but keeps working as a bridge. Precompiled projects must be rebuilt with the 2.0 Heddle.Generator; 1.x manifests are rejected by the engine-version gate and fall back (or throw under PrecompiledMismatchPolicy.Strict).

CI & packaging

Cross-platform test, workflow, and packaging failures resolved: RID-specific tool packing, LF-pinned golden fixtures, serialized multi-TFM runs (fixing a process-global singleton race), culture-pinned formatter tests, explicit .NET runtime installs, project-level symbol-package config, the VS Code extension TypeScript build, a trimmed-runtime string-op fallback surfaced by the WASM demo, and a warning-clean multi-TFM build. Contributor spec/roadmap material is excluded from the published docs site.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.