feat: add file-scoped recursive for loops

[Mohamed Mansour (mohamedmansour)]

Why

Render tree-shaped state by reusing one loop body instead of duplicating markup or introducing recursive component definitions.

Closes #518

Approach

<for id="tree-item" each="item in items">
  <h1>{{item.name}}</h1>
  <for id="tree-item" each="item in item.children" />
</for>

• Compile each named body once as <id>-<owner index>. References within that file reuse its protocol fragment and native client block index; other components can use the same ID independently.
• Evaluate the reference's collection in its parent scope, then shadow and restore the same item variable for each child. Forward references are supported. A second body produces duplicate-for-id; missing definitions and mismatched item names also fail at build time.
• Make CSS-token traversal cycle-safe without losing inherited scope information. Preserve component-asset/style discovery, keyed reconciliation, hydration, events, and client-created rendering.
• Reuse existing protocol fields and runtime behavior: no protocol schema changes or additional browser runtime JavaScript.

Compatibility

id replaces the legacy template attribute, which now produces a migration diagnostic. each accepts only unbraced syntax such as each="item in items". FAST component builds reject named references with an actionable diagnostic; SSR and the native WebUI client support them.

Validation

• cargo xtask check passed, including workspace tests, linting, dependency audit, protocol drift, native/WASM builds, examples, benchmark validation, and docs.
• Parser and handler unit regressions cover file isolation, fragment reuse, scope restoration, forward/mutual references, invalid syntax, duplicate definitions, and cyclic build traversal. Unit tests remain inline in their implementation files.
• All six recursive browser scenarios passed against a freshly rebuilt native addon, covering SSR, hydration, keyed updates, events, and client creation.
• Release directive benchmarks showed no ordinary-loop regression; representative client-template compilation measured 87.4 us before and 78.3 us after.

[Copilot]

🟡 Changes recommended

It contains at least one confirmed correctness/UX issue (nondeterministic/incorrect client-template diagnostic locations) plus a FAST validation bypass due to case-sensitive tag matching.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR introduces file-scoped named <for> bodies to enable recursive (and mutually recursive) loops by reusing a single compiled loop body within the same entry/component file, while keeping protocol shape stable and avoiding schema/runtime JS additions.

Changes:

• Add id="..." support for <for> to define/refer to a reusable loop body (including forward/mutual references) with build-time validation and new diagnostic codes.
• Enforce unbraced each="item in collection" parsing across SSR/native compilation paths, and reject legacy template naming with a migration diagnostic.
• Add cycle-safe traversal for CSS-token analysis with shared loop records; add extensive Rust + Playwright fixture coverage and documentation updates.

File summaries

File	Description
packages/webui-framework/tests/fixtures/recursive-repeat/state.json	Adds state fixture data for recursive/forward/independent/mutual loop scenarios.
packages/webui-framework/tests/fixtures/recursive-repeat/src/test-recursive-tree/test-recursive-tree.html	Defines a recursive named-loop tree rendering template with events and keys.
packages/webui-framework/tests/fixtures/recursive-repeat/src/test-recursive-mutual/test-recursive-mutual.html	Adds mutual named-loop reference fixture to validate finite traversal and scoping.
packages/webui-framework/tests/fixtures/recursive-repeat/src/test-recursive-independent/test-recursive-independent.html	Adds same-id independence fixture scoped per component/file.
packages/webui-framework/tests/fixtures/recursive-repeat/src/test-recursive-forward/test-recursive-forward.html	Adds forward-reference fixture (reference before definition).
packages/webui-framework/tests/fixtures/recursive-repeat/src/index.html	Fixture page wiring for Playwright coverage.
packages/webui-framework/tests/fixtures/recursive-repeat/recursive-repeat.spec.ts	Playwright coverage for SSR/no-JS render, hydration, keyed updates, events, and client-created recursion.
packages/webui-framework/tests/fixtures/recursive-repeat/element.ts	Defines observable element classes used by the recursive fixture tests.
docs/guide/concepts/directives/for.md	Documents recursive named loops, id rules, key inheritance, and each formatting constraints.
docs/ai.md	Updates AI guidance with named recursion rules and links to the canonical docs section.
DESIGN.md	Updates specification for <for> parsing/diagnostics and adds cycle-safe CSS token walk behavior notes.
crates/webui/src/lib.rs	Adds an end-to-end Rust build test to ensure recursive named loops don’t break component asset/style discovery.
crates/webui-parser/src/plugin/webui/named_repeats.rs	Introduces compile-time named-repeat block reuse + key inheritance + cycle-safe root analysis helper.
crates/webui-parser/src/plugin/webui.rs	Integrates named repeat compilation into WebUI template metadata emission; normalizes <if> condition braces.
crates/webui-parser/src/plugin/fast/v3.rs	Rejects named <for> references in FAST builds; normalizes <if> condition braces.
crates/webui-parser/src/plugin/fast/v2.rs	Same as v3: rejects named references; normalizes <if> condition braces.
crates/webui-parser/src/plugin/fast/shared.rs	Adds shared FAST validation to detect unsupported named <for> references.
crates/webui-parser/src/plugin/fast/diagnostic.rs	Adds fast-named-for-unsupported diagnostic with actionable guidance.
crates/webui-parser/src/lib.rs	Implements named loop scoping, ID collision checks, each parser reuse, brace-stripping for <if>, and cycle-safe token traversal.
crates/webui-parser/src/diagnostic.rs	Adds new diagnostic code constants for named-loop authoring errors.
crates/webui-handler/src/lib.rs	Adds SSR rendering regression tests covering recursion, scoping restore, missing children termination, and error behavior.

Review details

• Files reviewed: 21/21 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mddinbox]

ISSUE-001: Deduplicate equivalent shared-block analysis paths

Severity: 🟡 Performance — P2

Files: crates\webui-parser\src\plugin\webui.rs:1132–1136; crates\webui-parser\src\plugin\webui\named_repeats.rs:109–123.

The new ancestor-only guard prevents cycles but still visits every acyclic path through shared bodies, retaining a scope record per visit. Equivalent scopes therefore cause exponential build-time CPU and memory growth.

Reproduction: 22 named bodies, each referencing the next twice, produce just 2.8 KB of source. A release-mode real build took approximately 884 ms and 328 MiB peak working set, producing only 22 blocks and 2.5 KB of client metadata. Rendering with empty collections produced 25 bytes of HTML. The expensive work is redundant analysis, not required output.

Suggested fix: Memoize equivalent block/scope visits or compute free-root sets iteratively. Preserve distinctions between genuinely different scopes; block-only global deduplication would be incorrect.

Evidence: 1,451 affected Rust tests, 363 framework unit tests, E2E typechecking, all six recursive browser scenarios, and an additional 250-level client-created tree probe passed. All 35 current-head CI checks are green.

Existing recursive runtime calls are pre-existing, not another PR-introduced finding. Full local quality-gate/platform coverage and ordinary-loop performance claims were not independently verified.

[Mohamed Mansour (mohamedmansour)]

Accepted ISSUE-001 and fixed it in 1b6e2ff by memoizing equivalent block/bound-name-set visits in client-root and CSS-token analysis, preserving distinct lexical scopes, traversal order, cycle guards, and the ordinary-template fast path. Across seven fresh release-build processes, the 22-body reproduction improved from 875.33 ms/328.39 MiB to 0.87 ms/7.53 MiB (medians), with identical 22 blocks, 2,517-byte metadata, canonical protocol content, and 25-byte HTML; the new inline regressions fail without memoization, and 1,458 affected Rust tests, 363 framework unit tests, 37 repeat browser tests, E2E typechecking, and the full cargo xtask check gate pass.

[mddinbox]

Reviewed the latest head and the addressed feedback. The FAST case-insensitive validation, deterministic diagnostic locations, and shared-block scope memoization fixes are satisfactory. No remaining code-review blockers found.

[mddinbox]

Reviewed the latest merge commit and its conflict resolutions. The recursive CSS-token fixtures now correctly distinguish unconditional :root defaults from selector-scoped overrides, while retaining recursive asset/style and fallback-chain coverage. No new correctness, performance, memory, security, reliability, or dependency-impact blockers found.