Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .ai-factory/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ The model deliberately rejects deep DDD-style internal layering of the engine (a
## Decision Rationale

- **Project type:** GPU-accelerated UI framework + ecosystem (libraries), hard fork of `gpui-ce`.
- **Tech stack:** Rust (edition 2024, MSRV 1.85, target idioms of 1.95+ when stable), Cargo workspace, smol async runtime, wgpu/Metal/Direct3D 11, Taffy layout, cosmic-text/swash text.
- **Tech stack:** Rust (edition 2024, MSRV 1.95 — bumped in K99), Cargo workspace, smol async runtime, wgpu/Metal/Direct3D 11, Taffy layout, cosmic-text/swash text.
- **Key factor — three tiers:** A UI ecosystem has three distinct concerns: (A) what the GPU and OS do, (B) what the framework does to make widgets ergonomic, (C) what app authors compose. Conflating them creates exactly the problems the project hit before — engine bleed into widgets (Zed-style `div`-based UI) or framework bleed into engine (no place for `Widget`/`Key`/`State` to live).
- **Key factor — Cargo crates as the boundary:** Each tier is enforced by Cargo's dependency graph. A forbidden dependency would form a cycle and `cargo build` refuses to compile.
- **Alternative considered (rejected):** Clean Architecture — there is no business logic to invert dependencies around; the framework's "domain" is the rendering pipeline itself.
Expand Down Expand Up @@ -259,7 +259,7 @@ Window isolation is automatic. Theme, MediaQuery, DefaultTextStyle, Localization
8. **No `Rc<RefCell<…>>` on dispatch / tick / paint hot paths.** Owning structures + index-based references; runtime borrow checks belong outside hot loops.
9. **Async-safe by default.** Use `smol`-based primitives. `clippy.toml` enforces `smol::process::Command::*` over `std::process::Command::*`.
10. **`unimplemented!()` and `unreachable!()` are tracked, not ornamental.** Inventoried by S01a; classify before touching.
11. **MSRV 1.85.** Edition 2024. Target idioms of Rust 1.95+ when stable, document the bump explicitly when raising MSRV.
11. **MSRV 1.95.** Edition 2024. Three-file synchronization invariant: `Cargo.toml` `[workspace.package].rust-version`, `rust-toolchain.toml` `channel`, and `clippy.toml` `msrv` must agree. Document MSRV bumps explicitly (see K99 design spec for the precedent). Modern idioms unlocked by 1.95 (AFIT, RPITIT, edition-2024 lifetime captures, async closures, let-chains, `lazy_cell`, `unsafe extern`, `#[diagnostic::on_unimplemented]`) are encouraged where they improve clarity.
12. **Determinism on the GPU path.** Offscreen / golden-test outputs must remain reproducible; coordinate with the `wgpu-gpu-reviewer` agent for any change in `crates/flui-core/src/platform/wgpu/**`, `scene.rs`, the Metal renderer, or the DirectX renderer.
13. **Ecosystem KPI.** Public API of `flui-framework` is `cargo-semver-checks` clean. A third-party widget crate must be implementable against stable Framework API. This is the success metric for "Flutter ecosystem parity".

Expand Down
4 changes: 2 additions & 2 deletions .ai-factory/DESCRIPTION.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ The project is currently in Phase I of a multi-phase roadmap focused on (1) extr

## Tech Stack

- **Programming language:** Rust (edition 2024, MSRV 1.85)
- **Programming language:** Rust (edition 2024, MSRV 1.95 — bumped in K99)
- **Workspace resolver:** Cargo resolver = "3"
- **Async runtime:** smol
- **GPU / graphics:** wgpu, naga, metal (macOS), Direct3D 11 via `windows` crate, ash (Vulkan loader), Wayland (`wayland-client`) and X11 (`x11rb`) on Linux
Expand Down Expand Up @@ -65,5 +65,5 @@ Authoritative architectural and migration context lives in `docs/superpowers/spe
- **Async safety:** Clippy enforces `smol::process::Command::*` over `std::process::Command::*` to avoid blocking the executor thread.
- **Determinism:** GPU work targets deterministic offscreen rendering for golden tests; `lock-checks` tooling and `lock-coverage-gaps.md` track regressions.
- **Platform parity:** macOS (Metal), Windows (Direct3D 11), Linux (wgpu + Wayland + X11) are all first-class targets; iOS/Android/WASM are roadmap items.
- **MSRV:** Rust 1.85 (edition 2024).
- **MSRV:** Rust 1.95 (edition 2024). Enforced via three synchronized locations: `Cargo.toml` `[workspace.package].rust-version`, `rust-toolchain.toml` `channel`, `clippy.toml` `msrv`. CI gate: standard jobs (check / clippy / test / format) honor the pin via `rust-toolchain.toml`; a non-blocking `forward-compat` job runs latest stable as an early-warning radar for upcoming Rust changes. flake.nix uses `fenix.latest` (intentionally divergent — Nix users get forward-compat radar; rustup users stay pinned to MSRV).
- **Spelling discipline:** `typos.toml` is enforced.
4 changes: 2 additions & 2 deletions .ai-factory/RESEARCH.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Status: active

**Topic:** Strategic alignment of flui-v2 toward "Flutter ecosystem on Rust" — reconciling vision with current architecture and prior abandoned attempts.

**Goal:** Build a full UI engine in Rust with a Flutter-equivalent ecosystem and developer experience, leveraging Rust 1.85+ idioms (target 1.95+ when stable), GPUI as the engine substrate, and community libraries (wgpu, taffy, cosmic-text). Performance and safety advantages over Flutter come from Rust ownership and zero-cost abstractions.
**Goal:** Build a full UI engine in Rust with a Flutter-equivalent ecosystem and developer experience, leveraging Rust 1.95 idioms (AFIT/RPITIT, edition-2024 lifetime captures, async closures, let-chains, lazy_cell, unsafe extern, `#[diagnostic::on_unimplemented]`), GPUI as the engine substrate, and community libraries (wgpu, taffy, cosmic-text). Performance and safety advantages over Flutter come from Rust ownership and zero-cost abstractions.

**Goal is "feature surface", not "internal layering":** the project intentionally does NOT replicate Flutter's 4-tree internal model (Widget/Element/RenderObject/Layer). The earlier `flui` v1 attempt (`C:\Users\vanya\RustroverProjects\flui`) tried that and was abandoned due to multi-tree complexity. Decision is final — we build on top of GPUI's single-tree engine.

Expand Down Expand Up @@ -61,7 +61,7 @@ State is NOT a tree — it's a flat map keyed by `ElementId`. Reconciliation ope
- Breaking changes are allowed (no semver promise yet) — both internal and from upstream gpui-ce.
- 60 FPS is a structural property — Framework layer must not allocate on rebuild hot path; reconciliation must be O(siblings), not O(tree).
- `Rc<RefCell<...>>` forbidden on dispatch/tick/paint hot paths (per `docs/promt.md` §3.1).
- Edition 2024, MSRV 1.85, target idioms of Rust 1.95+ when available.
- Edition 2024, MSRV 1.95 (bumped in K99, 2026-05-08).

**Fork positioning (NEW — critical context):**

Expand Down
3 changes: 2 additions & 1 deletion .ai-factory/ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ Numbering convention:

#### K-track: critical chain (sequential)

- [ ] **K99 MSRV bump to Rust 1.95+** — workspace Cargo.toml, rust-toolchain.toml, CI matrix update. Unlocks: AFIT + RPITIT + edition-2024 lifetime captures (allow `Widget::build(&self) -> impl Widget` without `Box<dyn>`), async closures stable, `let-chains` stable, `lazy_cell` stable. Single-PR mechanical change. **Prerequisite for all subsequent K-specs.**
- [x] **K99 MSRV bump to Rust 1.95+** — workspace Cargo.toml, rust-toolchain.toml, CI matrix update. Unlocks: AFIT + RPITIT + edition-2024 lifetime captures (allow `Widget::build(&self) -> impl Widget` without `Box<dyn>`), async closures stable, `let-chains` stable, `lazy_cell` stable. Single-PR mechanical change. Spec: `docs/superpowers/specs/2026-05-08-K99-msrv-bump-1.95-design.md`. **Prerequisite for all subsequent K-specs.**
- [ ] **K15 Re-entrancy contract** — document and enforce semantics for `update_window` inside `update_window`, `update_entity` inside callback, `setState` inside `did_update_widget`. Either queue (preferred) or panic with structured error (acceptable). No undefined `RefCell::borrow_mut` panics. Adds property-tests covering re-entry scenarios. **HIGH-RISK** — touches every callback in the system.
- [ ] **K07 AppCell removal — token-based borrow model** — replaces `AppCell = RefCell<App>` (marked "remove after stabilization") with token-based mutual-exclusion. Closes E3 from `docs/promt.md`. **HIGH-RISK** — every callback signature changes.
- [ ] **K05 Element trait → context object** — `&mut PaintCx<'_>` / `&mut LayoutCx<'_>` / `&mut PrepaintCx<'_>` replace 6-7-arg method signatures. Closes E5, E6 from `docs/promt.md`. **API-BREAKING** for every custom Element. Unblocks K01-K04 by giving them clean borrow surfaces.
Expand Down Expand Up @@ -205,6 +205,7 @@ Numbering convention:
| S07.5 GestureArena T15 follow-up (RecognizerLifecycle, back-channel, hold/release, per-window settings, end-to-end test, contributor doc) | 2026-05-07 |
| S07.5b GestureArena pre-roster cleanup (PointerEvent surface upgrade, Affine2 + HitTestScope RAII, DeliveredEvent, unified back-channel hook + per-pointer LongPress storage, hold_count counter, AllowedButtonsFilter, CHANGELOG.md) | 2026-05-07 |
| S21 Animation Flutter parity (Animation<T> trait + listeners + Ticker, Curve trait family + Curves catalogue, Animatable + Tween family + TweenSequence, combinators, CurvedAnimation, controller polish, flui-animate skeleton removed) | 2026-05-08 |
| K99 MSRV bump to Rust 1.95 (workspace Cargo.toml + rust-toolchain.toml + clippy.toml msrv field; per-member rust-version inheritance for all 12 workspace members; CI converted to MSRV-enforced via rust-toolchain.toml + new non-blocking forward-compat job; AGENTS/DESCRIPTION/ARCHITECTURE/RESEARCH/rules docs aligned; FREEZE Cargo.lock policy; flake.nix divergence documented). First Phase 0-K spec. Unblocks K15 → K07 → K05 → K01 → K02 → K03 → K04 critical chain. | 2026-05-08 |

## Cross-track dependencies

Expand Down
Loading
Loading