fusee-framework 1.8.0 → 1.9.0

package/ghid_rust_fusee_rust_1_95_0.txt

@@ -0,0 +1,1118 @@
+GHID COMPLET RUST 1.95.0 PENTRU FUSEE
+De la 0 la un compilator JS/Rust/WASM pentru un framework cu fine-grained reactivity
+
+Autor: ChatLLM
+Limba: Romana
+Format: ghid practic, orientat spre arhitectura, bune practici si evitarea greselilor tipice
+
+============================================================
+0. SCOPUL GHIDULUI
+============================================================
+
+Acest document este gandit pentru cazul tau concret:
+- esti student la CS;
+- construiesti Fusee, un framework JS inspirat in principal din Solid si Vue;
+- ai in vedere fine-grained reactivity;
+- vrei mai intai un compilator/procesor AST scris in JavaScript;
+- apoi vrei o versiune scrisa in Rust care compileaza la WASM si ruleaza in browser;
+- vrei un ghid bun si realist, nu un text generic despre Rust.
+
+Obiectivul acestui ghid este dublu:
+1) sa te invete Rust de la fundamente pana la un nivel suficient pentru a construi infrastructura serioasa de compilator;
+2) sa functioneze si ca “document de orientare” pentru un editor AI, astfel incat acesta sa nu faca greseli lamentabile cand scrie Rust pentru proiectul tau.
+
+Acesta nu este doar un curs de sintaxa. Este o harta de drum pentru a trece de la “invata Rust” la “proiectez componente de compilator si WASM fara sa imi sabotez arhitectura”.
+
+============================================================
+1. DE CE RUST PENTRU FUSEE
+============================================================
+
+Rust este o alegere foarte buna pentru partea a doua a proiectului tau din cateva motive:
+
+1. Performanta predictibila
+- fara GC de runtime;
+- fara pauze de colectare;
+- foarte bun pentru parsare, analiza semantica, transformari si codegen.
+
+2. Siguranta memoriei
+- extrem de importanta pentru compilatoare si infrastructura care proceseaza multe structuri de date;
+- reduce clase intregi de bug-uri fata de C/C++.
+
+3. Model excelent pentru toolchain-uri
+- CLI-uri rapide;
+- biblioteci usor de compus;
+- integrare buna cu WASM;
+- ecosistem matur pentru parsare, erori, testare si profiling.
+
+4. Potrivire buna cu un compilator modern de frontend
+- poti scrie un parser nativ foarte rapid;
+- poti compila partea “grea” la WASM si o poti rula in browser;
+- poti separa clar frontend API-ul JS de motorul de compilare din Rust.
+
+5. Se potriveste cu tipul de arhitectura vazut in industrie
+Modelele care merita studiate conceptual sunt:
+- Babel: flexibilitate mare, ecosistem de transformari, model AST-centric in JS;
+- TypeScript compiler: pipeline clar parser -> binder -> checker -> emitter;
+- SWC: viteza si separare clara intre parse/transform/codegen;
+- Biome: infrastructura foarte disciplinata pentru parser, formatter, linter;
+- Oxc: accent pe performanta si toolchain JS modern in Rust;
+- Vue compiler: split clar intre template parse, transform si codegen;
+- Solid compiler: transformari orientate pe semantica reactivitatii si granularitate fina.
+
+Pentru Fusee, ideea buna nu este sa copiezi 1:1 un proiect, ci sa combini:
+- ergonomia si pipeline-ul configurabil din Babel/Vue;
+- disciplina de date si performanta din SWC/Biome/Oxc;
+- gandirea orientata pe reactivitate fina din Solid.
+
+============================================================
+2. CE TREBUIE SA STIE UN EDITOR AI DESPRE RUST, CA SA NU TE INCURCE
+============================================================
+
+Aceasta sectiune este foarte importanta. Daca dai acest document unui editor AI, el ar trebui sa respecte regulile de mai jos.
+
+2.1. Reguli nenegociabile
+
+1) Sa nu propuna unsafe fara motiv serios.
+- Infrastructura de compilator se poate scrie foarte bine in safe Rust.
+- unsafe este ultima optiune, nu prima.
+
+2) Sa nu foloseasca clone() ca plasture universal.
+- clone() peste tot ascunde defecte de design.
+- Mai intai se cauta imprumuturi (&T), slice-uri, indici, interner-e sau ownership clar.
+
+3) Sa nu foloseasca Rc<RefCell<T>> ca default.
+- Este tentant pentru cine vine din JS, dar adesea strica designul.
+- Pentru AST si pipeline de compilare, modele mai bune sunt:
+  - ownership pe arbore;
+  - arena allocation mai tarziu, daca chiar ajuta;
+  - ID-uri stabile in loc de grafuri cu ownership circular.
+
+4) Sa prefere enum-uri si match in loc de ierarhii artificiale de clase.
+- Rust exceleaza cu algebraic data types.
+- AST-ul si diagnosticele trebuie modelate natural cu enum + struct.
+
+5) Sa trateze Result si Option explicit.
+- Fara unwrap() in cod de productie pe input de utilizator.
+- In parser si compiler, erorile fac parte din produs.
+
+6) Sa nu supra-generalizeze prea devreme.
+- Nu introduce trait-uri, generic overload si macro-uri doar ca “sa fie elegant”.
+- Un compilator bun incepe adesea concret si devine generic doar unde exista nevoie reala.
+
+7) Sa nu amestece tipurile pentru faze diferite.
+- Token != AST node != HIR node != diagnostic != generated output.
+- Fiecare faza trebuie sa aiba structuri clare.
+
+8) Sa nu inventeze API-uri de crate-uri.
+- Daca foloseste o librarie externa, trebuie sa verifice API-ul real.
+- Daca nu e sigur, mai bine propune pseudocod sau cere validare.
+
+9) Sa nu introduca async daca nu exista nevoie reala.
+- Parsing, transformare, codegen si WASM bindings nu cer automat async.
+- Async inutil complica tipurile si debugging-ul.
+
+10) Sa favorizeze designul orientat pe date.
+- Pentru compilatoare, structurile compacte, spans, ID-uri si tabele sunt adesea mai bune decat obiecte “smart”.
+
+2.2. Cum ar trebui sa gandeasca un editor AI cand scrie Rust pentru Fusee
+
+Ordinea corecta de gandire este:
+1) care e modelul de date?
+2) care este ownership-ul?
+3) care sunt input-urile si output-urile fazei?
+4) cum se raporteaza erorile?
+5) care sunt invariantiile?
+6) unde devine utila optimizarea?
+
+Ordinea gresita este:
+1) hai sa facem tot generic;
+2) hai sa folosim macros si lifetimes complicate;
+3) hai sa bagam Rc<RefCell<...>>;
+4) hai sa rezolvam borrow checker-ul cu clone();
+5) hai sa optimizam inainte sa existe benchmark.
+
+2.3. Prompt intern bun pentru AI
+
+Cand il pui pe AI sa scrie Rust pentru Fusee, vrei sa il fortezi sa respecte idei de tipul:
+- modeleaza datele intai;
+- prefera enum + struct;
+- evita clone inutile;
+- evita unsafe;
+- returneaza Result cu erori explicite;
+- foloseste spans pentru noduri parse-uite;
+- separa parsing de semantic analysis si codegen;
+- nu presupune API-uri neverificate.
+
+============================================================
+3. ROADMAP RECOMANDAT PENTRU TINE
+============================================================
+
+Faza A. Invata Rust corect
+- ownership;
+- borrowing;
+- lifetimes la nivel practic;
+- enum, match, traits, iterators, modules, tests.
+
+Faza B. Scrie unelte mici
+- tokenizer simplu;
+- parser pentru expresii;
+- evaluator mic;
+- CLI cu fisiere si erori.
+
+Faza C. Scrie un parser/transformer in JavaScript
+- defineste AST-ul Fusee;
+- stabileste pipeline-ul;
+- valideaza designul limbajului si al transformarii.
+
+Faza D. Rescrie parserul si infrastructura critica in Rust
+- lexer;
+- parser;
+- spans;
+- diagnostics;
+- AST/HIR;
+- codegen minim.
+
+Faza E. Compileaza la WASM
+- expune un API mic si stabil catre JS;
+- ruleaza parserul/compilatorul in browser;
+- evita sa treci volume mari de date peste granita JS/WASM.
+
+Faza F. Optimizeaza pe baza de benchmark
+- parser throughput;
+- memorie;
+- code size WASM;
+- latenta in browser.
+
+============================================================
+4. SETUP MODERN RUST 1.95.0
+============================================================
+
+Pe baza anuntului oficial Rust 1.95.0, versiunea a fost lansata pe 16 aprilie 2026.
+
+Instalare si update:
+- instaleaza prin rustup;
+- update la stable cu: rustup update stable
+
+Practic, pentru proiectul tau:
+- foloseste stable, nu nightly, ca baza;
+- daca experimentezi, izoleaza clar orice dependenta pe nightly;
+- seteaza edition = "2024" in Cargo.toml pentru proiectele noi;
+- defineste un MSRV clar doar daca vei publica librarii serioase pentru altii.
+
+Un setup sanatos:
+- rustup
+- cargo
+- rustfmt
+- clippy
+- target WASM cand ajungi acolo
+- optional: cargo-nextest, criterion, wasm-pack, wasm-bindgen-cli daca ai nevoie de flux explicit
+
+Comenzi utile:
+- rustup update stable
+- cargo new fusee-playground
+- cargo test
+- cargo fmt
+- cargo clippy --all-targets --all-features -- -D warnings
+- cargo doc --open
+
+Politica recomandata:
+- fmt obligatoriu;
+- clippy obligatoriu in CI;
+- testele sa ruleze la fiecare schimbare importanta;
+- fara warnings tolerate la nesfarsit.
+
+============================================================
+5. FUNDAMENTELE RUST PE CARE TREBUIE SA LE STAPANESTI
+============================================================
+
+5.1. Ownership
+
+Ideea centrala:
+- fiecare valoare are un proprietar;
+- cand proprietarul dispare din scope, valoarea este eliberata;
+- mutarea ownership-ului este explicita prin semantica limbajului.
+
+De ce conteaza pentru compilatoare:
+- AST-uri, token streams, string-uri si buffer-e trebuie mutate sau imprumutate constient;
+- daca nu stapanesti ownership, vei “lupta” cu borrow checker-ul in loc sa il folosesti.
+
+Ce sa inveti practic:
+- mutare vs copiere;
+- tipuri Copy vs non-Copy;
+- cand sa detii String si cand sa folosesti &str.
+
+Regula practica:
+- la granita API-ului, detine datele cand are sens;
+- intern, imprumuta cat poti, dar nu exagera cu lifetimes complexe daca un ownership clar este mai simplu.
+
+5.2. Borrowing
+
+Borrowing inseamna acces temporar la o valoare fara transfer de ownership.
+- &T = imprumut imutabil;
+- &mut T = imprumut mutabil.
+
+Regula de baza:
+- poti avea multe imprumuturi imutabile sau unul mutabil, nu ambele simultan.
+
+Pentru Fusee:
+- parserul poate imprumuta sursa de intrare;
+- diagnosticele pot referi spans, nu neaparat copii de substring-uri;
+- transformatorii ar trebui proiectati sa evite aliasing mutabil complicat.
+
+5.3. Lifetimes
+
+Nu trebuie sa devii fanatic al lifetime-urilor de la inceput.
+Trebuie doar sa intelegi:
+- lifetime-ul descrie cat timp o referinta este valida;
+- multe lifetime-uri sunt inferate;
+- lifetime-urile explicite devin relevante cand returnezi referinte sau cand legi mai multe referinte intre ele.
+
+Recomandare pentru incepator in compilatoare:
+- nu construi AST-ul initial ca o padure de referinte &str peste tot;
+- mai simplu este adesea:
+  - input-ul ramane un String sau Arc<str> la nivel de fisier;
+  - nodurile tin spans / offset-uri;
+  - extragerea textului original se face la nevoie.
+
+Aceasta strategie reduce dramatic complexitatea lifetime-urilor.
+
+5.4. Struct si enum
+
+Acestea sunt fundamentul pentru orice compilator serios in Rust.
+
+Exemplu mental:
+- TokenKind = enum;
+- Token = struct { kind, span };
+- Expr = enum cu variante precum Identifier, Call, Binary, Literal;
+- Module = struct cu lista de itemi.
+
+De ce enum este atat de bun:
+- modelare precisa a limbajului;
+- exhaustivitate la match;
+- mai putine bug-uri ascunse.
+
+5.5. Pattern matching
+
+match este una dintre cele mai importante unelte din Rust.
+Pentru parsare si analiza:
+- pe token kinds;
+- pe node kinds;
+- pe erori;
+- pe stari de compilare.
+
+Rust 1.95.0 aduce if-let guards in match, ceea ce este util pentru logica mai expresiva in ramurile de match. Este o imbunatatire reala, dar nu trebuie abuzata: lizibilitatea ramane prioritatea.
+
+5.6. Option si Result
+
+Option<T>
+- exista sau nu exista o valoare.
+
+Result<T, E>
+- operatie reusita sau eroare.
+
+Pentru compilatoare:
+- parserul rar este “doar bool”; el trebuie sa produca fie noduri, fie erori sau recoveries;
+- diagnostics-urile si error recovery sunt mult mai importante decat in multe alte tipuri de aplicatii.
+
+Buna practica:
+- foloseste tipuri de eroare dedicate;
+- nu face panic! pe input invalid al utilizatorului;
+- foloseste context clar in erori.
+
+5.7. Traits
+
+Trait-urile sunt asemanatoare interfetelor conceptual, dar mai puternice.
+Le vei folosi pentru:
+- visitors;
+- pretty printers;
+- abstrahii de codegen;
+- conversii controlate;
+- helper-e generice.
+
+Avertisment:
+- nu transforma totul in trait din prima saptamana;
+- in compilatoare, structuri concrete + functii clare sunt adesea mai bune la inceput.
+
+5.8. Iterators si colectii
+
+Trebuie sa stii bine:
+- Vec<T>
+- String
+- HashMap<K, V>
+- BTreeMap<K, V>
+- slices
+- iter(), iter_mut(), into_iter()
+
+Buna practica:
+- foloseste Vec ca structura de baza implicita;
+- optimizezi ulterior doar dupa benchmark;
+- pentru tabele de simboluri, HashMap este suficient la inceput.
+
+5.9. Module si crate-uri
+
+Un proiect sanatos in Rust are separare buna in module.
+Nu vrei un singur fisier cu 5000 linii.
+
+Structura minima buna:
+- lexer.rs
+- parser.rs
+- ast.rs
+- span.rs
+- diagnostics.rs
+- lib.rs
+- main.rs sau bindings wasm separat
+
+============================================================
+6. BUNE PRACTICI DE RUST CARE CONTEAZA INTR-UN COMPILATOR
+============================================================
+
+1) Favorizeaza tipuri mici si clare.
+2) Tine spans peste tot unde input-ul provine din sursa.
+3) Evita string-uri duplicate inutil.
+4) Fii explicit cu invariantiile.
+5) Scrie teste pe fiecare faza.
+6) Separa parsing de validare semantica.
+7) Fii atent la API-ul public al crate-urilor.
+8) Nu expune internals gratuit.
+9) Foloseste documentatie si exemple scurte pe functiile publice.
+10) Masoara inainte de a micro-optimiza.
+
+Idiom-uri bune:
+- functii mici cu nume clare;
+- newtype-uri pentru ID-uri semnificative;
+- From/TryFrom unde conversiile sunt naturale;
+- Default doar unde are sens semantic;
+- Display pentru mesaje user-facing, Debug pentru dezvoltare.
+
+Idiom-uri rele:
+- bool-uri ambigue in loc de enum;
+- functii care returneaza tuple misterioase cu 4 campuri;
+- unwrap in cod care proceseaza fisiere reale;
+- macro-uri inutile pentru a ascunde logica.
+
+============================================================
+7. UNELTE SI CRATE-URI PE CARE MERITA SA LE AI IN VEDERE
+============================================================
+
+Nu trebuie sa le folosesti pe toate din prima.
+Le grupez pe rol.
+
+Pentru baza:
+- thiserror pentru tipuri de eroare ergonomice;
+- anyhow doar pentru binare/CLI la margine, nu neaparat in miezul compilatorului;
+- serde / serde_json pentru serializare, debug sau interop;
+- tracing si tracing-subscriber pentru logging serios.
+
+Pentru diagnostice:
+- miette sau codespan-reporting, daca vrei mesaje si spans frumoase;
+- alternativ, sistem propriu minimal la inceput.
+
+Pentru testare/benchmark:
+- cargo test;
+- criterion pentru benchmark-uri serioase.
+
+Pentru WASM:
+- wasm-bindgen;
+- wasm-pack;
+- web-sys sau js-sys doar daca ai nevoie de interop mai bogat cu browserul.
+
+Pentru performanta ulterioara:
+- bumpalo sau alte arene, dar doar dupa profilare;
+- rustc-hash sau indexmap daca ai motive concrete.
+
+Recomandare importanta:
+- incepe cu standard library cat mai mult;
+- adauga crate-uri dupa ce intelegi exact ce problema rezolva.
+
+============================================================
+8. CUM SA ITI STRUCTUREZI PROIECTUL FUSEE IN RUST
+============================================================
+
+8.1. Varianta simpla pentru inceput
+
+Incepe cu un singur crate de librarie si eventual un crate binar.
+De exemplu:
+- fusee_compiler/
+  - src/ast.rs
+  - src/span.rs
+  - src/token.rs
+  - src/lexer.rs
+  - src/parser.rs
+  - src/diagnostics.rs
+  - src/codegen.rs
+  - src/lib.rs
+  - src/main.rs
+
+Avantaje:
+- viteza mare de invatare;
+- mai putina frictiune organizatorica;
+- simplu de refactorizat la inceput.
+
+8.2. Varianta buna dupa ce proiectul creste
+
+Muti intr-un workspace cu crate-uri separate.
+Sugestie rezonabila:
+- fusee-span
+- fusee-diagnostics
+- fusee-token
+- fusee-lexer
+- fusee-ast
+- fusee-parser
+- fusee-hir
+- fusee-codegen-js
+- fusee-wasm
+- fusee-cli
+
+Nu trebuie sa faci asta in ziua 1.
+Workspace-ul devine valoros dupa ce ai claritate pe faze.
+
+8.3. Principiu de arhitectura
+
+Fiecare faza trebuie sa aiba:
+- input clar;
+- output clar;
+- tipuri proprii;
+- erori clare;
+- teste independente.
+
+Exemplu:
+- lexer: &str -> Vec<Token> + diagnostics
+- parser: &[Token] -> AST + diagnostics
+- analyzer: AST -> HIR + diagnostics
+- transform: HIR -> HIR optimizat / IR
+- codegen: IR/HIR -> JS/WASM-adjacent output
+
+============================================================
+9. DESIGNUL AST-ULUI PENTRU FUSEE
+============================================================
+
+Aici se fac multe greseli de incepator. Principiile bune:
+
+9.1. Fiecare nod trebuie sa aiba span
+
+Nu sari peste spans.
+Span-ul este crucial pentru:
+- erori;
+- source maps;
+- debug;
+- tooling;
+- IDE integration ulterioara.
+
+Model simplu:
+- Span { start: u32, end: u32 }
+
+9.2. Separa sintaxa de semantica
+
+AST-ul este despre forma sursei.
+HIR-ul sau o forma intermediara semantica este despre sens dupa rezolvari si validari.
+
+Nu baga direct in AST informatii precum:
+- simbol rezolvat final;
+- slot de runtime;
+- optimizari de codegen.
+
+9.3. Nu aglomera nodurile cu date duplicate
+
+Exemplu prost:
+- Identifier tine si string, si substring, si index, si span, si varianta lowercased, si pointer spre symbol.
+
+Exemplu bun:
+- Identifier tine text internat sau String/SmolStr si span;
+- resolverul produce mapping spre SymbolId separat.
+
+9.4. Fa node kinds clare
+
+Pentru un limbaj/framework cu template sau JSX-like syntax, separa bine:
+- expression nodes;
+- statement nodes;
+- declarations;
+- template nodes / DOM-ish nodes daca limbajul tau le are;
+- directives/annotations daca ai transformari reactive speciale.
+
+9.5. Gandeste AST-ul pentru recoverability
+
+Parserul pentru unelte de dezvoltare nu trebuie doar sa “esueze”.
+Trebuie sa poata recupera partial, astfel incat:
+- sa raporteze mai multe erori;
+- sa permita tooling incremental;
+- sa nu cada la primul caracter gresit.
+
+============================================================
+10. LEXER + PARSER: PRIMA IMPLEMENTARE SERIOASA
+============================================================
+
+10.1. Lexer
+
+Rol:
+- transforma textul in tokeni.
+
+Ce trebuie sa produca:
+- TokenKind;
+- span;
+- optional trivia separata sau tratata distinct.
+
+Decizie importanta:
+- daca vrei formatter/linter serios in viitor, trivia (whitespace/comments) conteaza.
+- daca vrei doar compilator minim, poti incepe fara modelare elaborata a trivia.
+
+10.2. Parser
+
+Rol:
+- construieste AST-ul din tokeni.
+
+Recomandare:
+- incepe cu recursive descent pentru claritate;
+- foloseste Pratt parser pentru expresii daca ai operatori cu precedenta.
+
+Pentru limbaje de frontend si DSL-uri de template, asta este o alegere foarte practica.
+
+10.3. Error recovery
+
+Trebuie sa ai o strategie de sincronizare.
+Exemple:
+- sari pana la ;
+- sari pana la }
+- sari pana la sfarsit de linie in anumite contexte
+
+Fara error recovery, experienta de developer va fi slaba.
+
+10.4. Parser API bun
+
+Un API bun evita sa expuna prea mult din internals.
+Exemplu conceptual:
+- parse_module(source: &str) -> ParseResult<Module>
+
+Unde ParseResult poate contine:
+- root AST;
+- diagnostics;
+- eventual flag de success partial.
+
+============================================================
+11. DIAGNOSTICE BUNE: DIFERENTA DINTRE O JUCARIE SI UN TOOL SERIOS
+============================================================
+
+Daca vrei ca Fusee sa fie respectabil, trateaza diagnosticele ca produs.
+
+Un diagnostic bun include:
+- severitate: error/warning/note;
+- mesaj principal clar;
+- span principal;
+- mesaje secundare sau labels unde ajuta;
+- sugestie de fix unde este posibil.
+
+Principii:
+- mesajele trebuie sa explice problema, nu doar sa repete starea interna;
+- evita jargonul intern fara sens pentru utilizator;
+- pastreaza consistenta de wording.
+
+Exemplu bun:
+- “Atributul reactive:each asteapta o expresie iterabila.”
+Nu:
+- “Invalid node in transform pass.”
+
+============================================================
+12. ANALIZA SEMANTICA SI REACTIVITATEA FINA
+============================================================
+
+Aici proiectul tau devine interesant conceptual.
+Pentru un framework inspirat de Solid/Vue, compilatorul nu doar parseaza; el decide ce parti sunt reactive, ce dependinte exista si cum generezi output eficient.
+
+Intrebari de arhitectura pe care trebuie sa le fixezi devreme:
+- ce este o sursa reactiva in Fusee?
+- cum detectezi citiri reactive?
+- cum separi evaluarea la compile-time de runtime?
+- cand generezi subscriptions, effects sau memo-uri?
+- cum tratezi template expressions, closures si nested scopes?
+
+Recomandare puternica:
+- nu incerca sa pui toata semantica direct in parser;
+- parserul construieste forma;
+- analyzerul semantic decide intentia reactiva.
+
+Pentru acest pas, o forma intermediara HIR este foarte utila.
+HIR-ul poate normaliza:
+- sugar sintactic;
+- directii reactive;
+- forme speciale de template;
+- binding-uri si scoping.
+
+============================================================
+13. CODEGEN: JS INTAI, APOI RUST/WASM
+============================================================
+
+13.1. Etapa JS
+
+Primul compilator in JS iti valideaza limbajul si transformarile.
+Asta e foarte bine. Il poti folosi ca laborator de semantica.
+
+Obiectivul in faza JS nu este viteza maxima, ci:
+- sa validezi AST-ul;
+- sa validezi transformarea reactiva;
+- sa validezi output-ul;
+- sa descoperi edge case-uri.
+
+13.2. Etapa Rust
+
+Cand treci la Rust, idealul nu este sa rescrii haotic totul.
+Trebuie sa porti o specificatie stabilizata:
+- aceleasi node kinds;
+- aceeasi semantica observabila;
+- teste de snapshot compatibile;
+- output comparabil.
+
+13.3. Codegen bun
+
+Un codegen bun:
+- nu concateneaza string-uri haotic;
+- are structuri intermediare clare;
+- separa emiterea de logica semantica;
+- pastreaza mapping pentru source map daca vei avea nevoie.
+
+Strategie simpla:
+- emiti intr-un String buffer cu helper-e de indentare;
+- mai tarziu poti trece la writer mai disciplinat sau IR textual.
+
+============================================================
+14. RUST -> WASM IN BROWSER
+============================================================
+
+Aici sunt cateva decizii importante.
+
+14.1. Ce compilezi la WASM
+
+Nu tot proiectul trebuie automat dus in WASM.
+Candidati buni:
+- lexer;
+- parser;
+- analyzer;
+- compilare de string sursa -> output.
+
+Candidati mai putin buni initial:
+- integrarea UI;
+- orchestrare de bundler;
+- logica mare de filesystem.
+
+14.2. Granita JS/WASM
+
+Granita trebuie sa fie mica si stabila.
+API bun:
+- compile(source: string, options: object) -> result object
+
+API prost:
+- sute de apeluri fine-grained intre JS si WASM pentru fiecare nod.
+
+Regula importanta:
+- crossing-ul JS/WASM are cost;
+- transfera putine obiecte, mai mari si bine definite.
+
+14.3. Reprezentarea datelor peste granita
+
+Ai trei variante practice:
+1) string in, string/json out;
+2) string in, obiecte JS prin wasm-bindgen/serde;
+3) buffer-e binare mai compacte, mai tarziu.
+
+Pentru inceput, varianta 1 sau 2 este cea mai sanatoasa.
+
+14.4. Browser execution model
+
+Daca compilarea poate deveni grea:
+- ruleaza in Web Worker;
+- evita blocarea thread-ului principal;
+- masoara dimensiunea finala a .wasm.
+
+14.5. Tooling comun
+
+Conform documentatiei Rust/WASM si MDN, fluxul comun foloseste wasm-pack si wasm-bindgen pentru a construi pachete consumabile din web. Pentru un proiect ca Fusee, aceasta este ruta naturala la inceput.
+
+============================================================
+15. PLAN DE INVATARE RUST, DE LA ZERO LA FUSEE
+============================================================
+
+ETAPA 1: Primele 2-3 saptamani
+Obiectiv: sa nu mai fii incepator total.
+
+Invata si exerseaza:
+- ownership;
+- borrowing;
+- structs, enums, match;
+- Option/Result;
+- Vec, String, HashMap;
+- modules;
+- tests.
+
+Mini-proiecte:
+- calculator CLI;
+- parser de expresii simple;
+- loader de fisiere cu erori bune.
+
+ETAPA 2: Urmatoarele 2-4 saptamani
+Obiectiv: sa poti scrie infrastructura decenta.
+
+Invata:
+- iterators;
+- pattern matching serios;
+- traits fara exces;
+- error types;
+- documentatie si testing discipline.
+
+Mini-proiecte:
+- lexer pentru un mini-limbaj;
+- parser cu precedenta operatorilor;
+- pretty-printer AST.
+
+ETAPA 3: 1-2 luni
+Obiectiv: sa poti construi un parser/compiler simplu.
+
+Invata:
+- spans si diagnostics;
+- recursive descent / Pratt parsing;
+- snapshot tests;
+- profiling si benchmark minimal.
+
+Mini-proiecte:
+- mini transpiler;
+- template parser;
+- semantic analyzer pentru scope-uri.
+
+ETAPA 4: proiect Fusee real
+Obiectiv: migratie controlata spre Rust + WASM.
+
+Construieste:
+- lexer;
+- parser;
+- diagnostics;
+- HIR;
+- transformari reactive;
+- codegen;
+- wasm bindings.
+
+============================================================
+16. CHECKLIST PENTRU PARTEA DE JS AST PARSER INITIALA
+============================================================
+
+Inainte sa scrii parserul Rust, valideaza aceste lucruri in implementarea JS:
+
+1) AST-ul are spans peste tot?
+2) Ai separare intre parse si transform?
+3) Ai teste pe input invalid?
+4) Ai output snapshots?
+5) Ai definit clar node kinds pentru sintaxa speciala Fusee?
+6) Ai o semantica clara pentru reactivitate?
+7) Ai identificat ce date trebuie pastrate pentru codegen?
+8) Ai delimitat ce apartine compilatorului vs runtime-ului?
+
+Daca raspunsul este “nu” la multe dintre acestea, nu te grabi la portarea in Rust.
+Rust nu repara neclaritatea de design; doar o face mai evidenta.
+
+============================================================
+17. CHECKLIST PENTRU MIGRAREA DIN JS IN RUST
+============================================================
+
+1) Exista o specificatie stabila a AST-ului?
+2) Exista corpus de teste si snapshot-uri?
+3) Exista exemple edge-case?
+4) Exista claritate asupra error recovery?
+5) Exista claritate asupra output-ului observabil?
+6) Exista o separare clara intre parser si transformari?
+7) Exista un minim API public pe care il vei expune in WASM?
+
+Migratia buna este:
+- intai parser compatibil;
+- apoi diagnostics compatibile;
+- apoi codegen compatibil;
+- apoi optimizari.
+
+============================================================
+18. ANTI-PATTERN-URI PE CARE SA LE EVITI
+============================================================
+
+1) Rescrierea totala prea devreme
+- Nu rescrie parserul JS in Rust inainte sa stii exact ce limbaj ai.
+
+2) Optimizare prematura
+- Arena allocation, string interning sofisticat, hashers speciali: toate vin dupa benchmark.
+
+3) AST prea “OO”
+- Rust nu e Java/C#; evita simularea ierarhiilor de clase cand enum rezolva natural problema.
+
+4) RefCell peste tot
+- Deseori semn ca ownership-ul nu e bine gandit.
+
+5) Lifetimes peste tot in AST
+- Pentru inceput, tine spans si input separat; iti simplifica enorm viata.
+
+6) Codegen amestecat cu semantic analysis
+- duce la cod greu de mentinut si testat.
+
+7) API WASM prea fin-grained
+- duce la overhead si design fragil.
+
+8) Diagnostic slab
+- face tool-ul sa para imatur chiar daca parserul e bun.
+
+============================================================
+19. STRATEGIE DE TESTARE
+============================================================
+
+Trebuie sa ai cel putin 5 tipuri de teste.
+
+1) Unit tests
+- pe lexer;
+- pe parser helper-e;
+- pe spans;
+- pe functii de transformare mici.
+
+2) Snapshot tests
+- AST output;
+- diagnostics;
+- generated code.
+
+3) Golden tests
+- fisiere de intrare -> fisiere de iesire asteptata.
+
+4) Error recovery tests
+- input invalid care totusi produce partial AST si multiple diagnostics.
+
+5) Differential tests (ideal mai tarziu)
+- compari implementarea JS cu cea Rust pe acelasi corpus.
+
+Asta este extrem de valoros pentru migrare.
+
+============================================================
+20. STRATEGIE DE PERFORMANTA
+============================================================
+
+Masori in ordine:
+1) corectitudine;
+2) ergonomie API;
+3) throughput parser;
+4) memorie;
+5) code size WASM;
+6) latenta in browser.
+
+Ce sa optimizezi de obicei mai intai:
+- allocatii excesive;
+- string-uri duplicate;
+- traversari redundante ale AST-ului;
+- crossing JS/WASM inutil;
+- serializare prea voluminoasa.
+
+Ce sa NU optimizezi din instinct:
+- fiecare bucla mica;
+- fiecare clonare, daca nu e hot path;
+- fiecare struct dupa “feeling”.
+
+============================================================
+21. CAND SA FOLOSESTI ARENE, INTERNING SI ID-URI
+============================================================
+
+Aceste tehnici sunt utile, dar vin cu cost conceptual.
+
+Arene
+- bune cand ai multe noduri cu durata similara de viata;
+- bune pentru performanta si localitate;
+- rele daca le introduci inainte sa stii unde este hot path-ul.
+
+String interning
+- bun pentru identificatori repetati;
+- util in symbol tables si comparisons;
+- nu obligatoriu in MVP.
+
+ID-uri stabile
+- foarte bune pentru a separa proprietatea datelor de referintele logice;
+- de multe ori mai sanatos decat grafuri de referinte complexe.
+
+Recomandare:
+- pentru MVP: structuri simple;
+- pentru versiuni serioase: ia in calcul SymbolId, NodeId si eventual internare selectiva.
+
+============================================================
+22. CUM SA ABORDEZI DESIGNUL REACTIV PENTRU FUSEE
+============================================================
+
+Din perspectiva compilatorului, fine-grained reactivity inseamna ca nu orice expresie trebuie tratata uniform.
+Ai nevoie de clasificari clare.
+
+De exemplu, vei vrea sa separi conceptual:
+- expresii pur statice;
+- expresii evaluate o singura data;
+- expresii reactive dependente de semnale/store-uri;
+- efecte cu side effects;
+- memo-uri / derivari;
+- bindings DOM care cer update punctual.
+
+Aici un analyzer semantic bun te ajuta mai mult decat un parser sofisticat.
+
+Intrebari de proiectare:
+- exista primitive dedicate in limbaj pentru reactivitate sau inferenta din usage?
+- reactivitatea este implicita sau explicita?
+- cum tratezi capturile in closure?
+- cum detectezi invalidarea minima?
+
+Aceste intrebari trebuie rezolvate la nivel de semantica si transform, nu doar la nivel de sintaxa.
+
+============================================================
+23. EXEMPLU DE ARHITECTURA MINIMA BUNA PENTRU FUSEE
+============================================================
+
+Pas 1: JS reference compiler
+- parser JS;
+- AST clar;
+- transform reactive;
+- codegen JS;
+- snapshot tests.
+
+Pas 2: Rust core library
+- lexer;
+- parser;
+- diagnostics;
+- AST;
+- parse API.
+
+Pas 3: semantic layer
+- scopes;
+- symbol resolution;
+- HIR;
+- clasificare reactiva.
+
+Pas 4: codegen parity
+- output compatibil cu implementarea JS de referinta.
+
+Pas 5: wasm package
+- compile(source, options) -> result;
+- worker integration;
+- pachet npm.
+
+Pas 6: optimizari si tooling
+- incremental ideas;
+- formatter/linter eventual;
+- source maps;
+- IDE support.
+
+============================================================
+24. NOTE SPECIFICE RUST 1.95.0 RELEVANTE PENTRU TINE
+============================================================
+
+Verificat din anuntul oficial Rust 1.95.0:
+- cfg_select! este stabilizat;
+- if-let guards in match sunt disponibile;
+- exista API-uri standard noi precum Vec::push_mut / insert_mut si analogi pentru VecDeque/LinkedList;
+- JSON target specs au fost destabilizate pe stable.
+
+Cum traduci asta practic pentru Fusee:
+- ramai pe stable cat poti;
+- evita dependenta pe configuratii exotice de target pe stable;
+- foloseste noile facilitati doar daca imbunatatesc claritatea, nu ca noutate cosmetica;
+- nu construi arhitectura pe detalii prea recente daca nu iti aduc un castig real.
+
+============================================================
+25. ORDINEA CORECTA A DECIZIILOR TEHNICE IN FUSEE
+============================================================
+
+1) defineste limbajul;
+2) defineste AST-ul;
+3) defineste semantica reactiva;
+4) construieste parserul de referinta in JS;
+5) construieste corpusul de teste;
+6) portare parser/diagnostics in Rust;
+7) portare analyzer/codegen;
+8) expunere WASM;
+9) profilare;
+10) optimizare.
+
+Daca inversezi aceasta ordine, te vei lovi de rescrieri dese.
+
+============================================================
+26. CE AS FACE EU, CONCRET, DACA AS FI IN LOCUL TAU
+============================================================
+
+Luna 1
+- invat Rust serios;
+- scriu 2-3 mini-proiecte;
+- imi definesc Span, Token, AST pentru Fusee.
+
+Luna 2
+- termin parserul JS de referinta;
+- stabilesc output-ul si semantica reactiva minima;
+- scriu snapshot tests.
+
+Luna 3
+- scriu lexer + parser in Rust;
+- fac diagnostice lizibile;
+- compar paritatea fata de JS.
+
+Luna 4
+- adaug semantic analysis;
+- adaug codegen compatibil;
+- fac primele benchmark-uri.
+
+Luna 5
+- compilez la WASM;
+- expun API minim pentru browser;
+- mut compilarea in worker daca e nevoie.
+
+Luna 6+
+- optimizez;
+- introduc interning / arene doar unde benchmark-ul justifica;
+- pregatesc eventual tooling suplimentar.
+
+============================================================
+27. REZUMAT EXECUTIV
+============================================================
+
+Daca retii doar cateva idei, sa fie acestea:
+
+1) Rust este excelent pentru partea de compilator si WASM din Fusee.
+2) Nu sari direct la Rust pana nu ai claritate suficienta asupra limbajului si a AST-ului.
+3) In Rust, designul de date si ownership-ul conteaza mai mult decat “trucurile”.
+4) Evita clone(), Rc<RefCell<...>> si unsafe ca solutii implicite.
+5) Pastreaza spans peste tot.
+6) Separa parserul de analiza semantica si de codegen.
+7) Tine granita JS/WASM mica.
+8) Testele si diagnosticele sunt parte din produs.
+9) Optimizeaza doar dupa benchmark.
+10) Foloseste implementarea JS ca specificatie executabila pentru portarea in Rust.
+
+============================================================
+28. SURSE SI REPERE VERIFICATE
+============================================================
+
+Surse oficiale / utile verificate pentru acest ghid:
+
+1) Anunt oficial Rust 1.95.0
+https://blog.rust-lang.org/2026/04/16/Rust-1.95.0/
+
+2) Release notes detaliate Rust 1.95.0
+https://doc.rust-lang.org/stable/releases.html#version-1950-2026-04-16
+
+3) Rust and WebAssembly Book
+https://rustwasm.github.io/docs/book/
+
+4) MDN - Compiling from Rust to WebAssembly
+https://developer.mozilla.org/en-US/docs/WebAssembly/Guides/Rust_to_Wasm
+
+5) AST Explorer, util pentru inspectie AST si invatare comparativa intre parsere
+https://astexplorer.net/
+
+6) Discutii si materiale introductive despre AST in JS, utile pentru perspectiva de ecosistem
+https://www.digitalocean.com/community/tutorials/js-traversing-ast
+https://stackoverflow.com/questions/16127985/what-is-javascript-ast-how-to-play-with-it
+
+============================================================
+29. CONCLUZIE FINALA
+============================================================
+
+Pentru Fusee, cea mai buna strategie nu este “scriu tot in Rust cat mai repede”, ci:
+- proiectez bine limbajul;
+- validez semantica in JS;
+- portez disciplinat in Rust;
+- expun nucleul prin WASM;
+- optimizez cand am masuratori.
+
+Daca respecti aceasta ordine, ai sanse reale sa ajungi la un tool modern, credibil si extensibil.
+Daca o ignori, risti sa construiesti un parser rapid pentru o semantica inca neclara.
+
+Rust te poate ajuta enorm, dar doar daca il folosesti ca instrument de claritate si disciplina, nu doar ca sursa de performanta.
+
+Sfarsit.