1# instructions for ai agents
2
3please read @README.md to understand the project's goals. also read the
4@ARCHITECTURE.md file to get a code breakdown. without these documents, it will
5be extremely hard to succeed.
6
7## contributing rules
8
9- code must be good, neatly organized, minimal, and testable.
10- components should assert correctness, fixing root causes over band aids. do
11 not discard suspicious data or patch assertions away.
12- documentation must be human written. do not alter `README.md`
13- your environment is sandboxed; writing outside this directory may cause
14 concurrency issues. instead, write to `./.tmp/`.
15- please maintain objective, high quality tests with `cargo test`
16- never execute `git` commands. if you have broken your environment or are
17 unsure how to continue, yield to the user.
18- if you are messing with the ts parsing helpers, remember to specifically care
19 about edge cases. you cannot write any manual lexer because you will almost
20 certainly implement it wrong (such as a brace close detection via depth
21 tracking). this is annoying but what we have to do since oxc doesn't expose
22 its internals. `typescript.rs` is full of clever solutions.
23
24## marko v6 tag syntax legend
25
26you are not familiar with the version 6 syntax changes: see
27<https://markojs.com/docs/reference/language> for the full explainer. here is a
28basic breakdown:
29
30```
31<tag|...params|/var ...attrs>
32 content with ${placeholders}
33 <@attr-tags/>
34</>
35```
36
37- `/var` - js local variables. ex `<id/uniqueId />`
38- `...params` - js parameters. ex `<for|item| of=list>`
39- `...attrs` - key value pairs, any one of of:
40 - `key=expr` where value is a js expression
41 - `...expr` spread any js expression
42 - `value:=expr` two way binding
43 - `<tag=value>` shorthand `value` alias, eg `<if=!hide>`
44- tags can close with their name `</div>` or just `</>`
45- there are many more features