docs(zo): update docs, add raylib examples, misc

.claude/agents/arm-architecture-expert.md

@@ -36,6 +36,8 @@ You are a world-class authority on the Arm architecture and an elite Rust system
   - https://developer.arm.com/documentation/ddi0487/mb — Arm Architecture Reference Manual for A-profile (the "Arm ARM", DDI 0487). Your primary spec. When you justify an encoding, cite the instruction's encoding diagram (e.g. "ADD (immediate) — sf|op|S|...|imm12|Rn|Rd"). Use WebFetch for sections.
   - AAPCS64 — the Procedure Call Standard for AArch64: argument/result registers, stack alignment, callee-saved set. Fetch when classifying arguments.
   - For Apple Silicon specifics (arm64e/arm64 differences, platform calling conventions), cross-check Apple's "Writing ARM64 Code for Apple Platforms".
+  - https://github.com/aidansteele/osx-abi-macho-file-format-reference
+  - https://github.com/apple-oss-distributions/xnu/blob/8d741a5de7ff4191bf97d57b9f54c2f6d4a15585/EXTERNAL_HEADERS/mach-o/loader.h
 
 ## Your code — know every line
 

README.md

@@ -12,7 +12,7 @@ zo (pronounced `/zuː/` just like "zoo") iS A PRACTiCAL, LiGHTWEiGHT, CROSS-PLAT
 
 **JOiN THE DEVOLUTiON.**
 
-[home](https://zo.compilords.house) — [install](./crates/compiler/zo-notes/public/guidelines/01-install.md) — [initiation](https://zo.compilords.house/initiation) — [news](https://zo.compilords.house/news) — [discord](https://discord.gg/JaNc4Nk5xw)
+[home](https://zo.compilords.house) — [install](./crates/compiler/zo-notes/public/guidelines/01-install.md) — [initiation](https://zo.compilords.house/initiation) — [spec](https://zo.compilords.house/spec) — [news](https://zo.compilords.house/news) — [discord](https://discord.gg/JaNc4Nk5xw)
 
 ## usage.
 
@@ -49,6 +49,7 @@ ONE LANGUAGE. ONE COMPiLER. ONE BiNARY. ONE WiNDOW. ALL PLATFORMS — SAME SOURC
 
 ---
 
+
 DEV MACHiNE:
 
 ```
@@ -65,7 +66,18 @@ Available Memory  — 9.4 GB
 > *This project is about having fun again. It is maintained by a small group of volunteers during their spare time. We're exploring. zo is not the new X or better than Y, zo is just different. Period. Be gentle.*
 
 > [!CAUTION]
-> *For transparency: regarding Ai usage, we're using Ai to build zo based on our architecture and specification (made by humans). The compiler currently covers over 1500 unit and integration tests.*
+> *For transparency: regarding Ai usage, we're using Ai to build zo based on our architecture and [specification](https://zo.compilords.house/spec) (made by humans). The compiler currently covers over 1500 unit and integration tests.*
+
+## gallery.
+
+<p align="center">
+  <img width="324px" src="crates/compiler/zo-notes/public/assets/preview/preview-zo-raylib-3d.gif">
+  <img width="324px" src="crates/compiler/zo-notes/public/assets/preview/preview-zo-raylib-arkanoid.gif">
+  <img width="324px" src="crates/compiler/zo-notes/public/assets/preview/preview-zo-raylib-asteroids.gif">
+  <img width="324px" src="crates/compiler/zo-notes/public/assets/preview/preview-zo-raylib-conway.gif">
+  <img width="324px" src="crates/compiler/zo-notes/public/assets/preview/preview-zo-raylib-mandelbrot.gif">
+  <img width="324px" src="crates/compiler/zo-notes/public/assets/preview/preview-zo-raylib-mouse.gif">
+</p>
 
 ## sponsors & supports.
 

apps/site/messages/de.json

@@ -7,19 +7,20 @@
   "benchmarks_title": "## benchmarks",
   "community_description": "Ein Spielplatz für Compiler-<b class='green-100'>Nerds</b>, Frontend-<b class='green-100'>Hacker</b> und <b class='green-100'>Kreative</b>. Öffne ein Issue, oder sag Hi auf <a href='https://discord.gg/JaNc4Nk5xw'>Discord</a>.",
   "community_title": "## gemeinschaft",
-  "features_fast_content": "Von Grund auf mit modernen Compiler-Techniken gebaut für <b class='green-100'>sofortige Ausführung</b> und schnelles Debugging mit <b class='green-100'>hilfreichen Fehlermeldungen</b>.",
+  "features_fast_content": "Von Grund auf mit modernen Compiler-Techniken gebaut für <b class='green-100'>sofortige Builds</b> und schnelles Debugging mit <b class='green-100'>hilfreichen Fehlermeldungen</b>.",
   "features_fast_title": "Schnell",
-  "features_integrated_content": "Eine komplette Workstation mit eingebauten Werkzeugen — Paketmanager <sup class='superscript green-100'><a href='https://github.com/invisageable/zo/blob/main/crates/packager/fret'>fret</a></sup> und Texteditor <sup class='superscript green-100'><a href='https://github.com/invisageable/codelord'>codelord</a></sup>.",
+  "features_integrated_content": "Eine komplette Workstation mit eingebauten Werkzeugen — Paketmanager <sup class='superscript green-100'><a href='https://github.com/invisageable/zo/blob/main/crates/packager/fret'>fret</a></sup> und Texteditor <sup class='superscript green-100'><a href='#'>codelord</a></sup>.",
   "features_integrated_title": "Integriert",
   "features_quote": "Weniger Arbeit machen, indem man keine Mühe verschwendet.",
-  "features_safe_content": "Statisch & stark typisiert. Nutzt Green- und OS-Threads, gekapselt in <b class='green-100'>nursery task scopes</b>; keine leaked threads, <b class='green-100'>keine data races</b>.",
+  "features_safe_content": "Statisch & stark typisiert, <b class='green-100'>ohne null</b> und ohne rohe Zeiger. Green- und OS-Threads laufen in <b class='green-100'>nursery task scopes</b> — keine leaked threads, <b class='green-100'>kein geteilter veränderbarer Zustand</b>.",
   "features_safe_title": "Sicher",
   "features_title": "## funktionen",
-  "features_unified_content": "Schreib Ui einmal mit ZSX — ziele auf nativ <sup class='superscript green-100'>gpu</sup> oder Web <sup class='superscript green-100'>dom</sup>.",
+  "features_unified_content": "Schreib Ui einmal mit ZSX — ziele auf Desktop <sup class='superscript green-100'>gpu</sup>, Mobile <sup class='superscript green-100'>uikit</sup> oder Web <sup class='superscript green-100'>dom</sup>.",
   "features_unified_title": "Einheitlich",
   "foundations_description": "Angetrieben von modernen, verlässlichen Fundamenten für eine <b class='green-100'>hochleistungsfähige</b> <b class='green-100'>Grafik</b>- und <b class='green-100'>Web</b>-Integration.",
   "foundations_title": "## fundamente",
   "header_initiation": "Einführung",
+  "header_spec": "Spec",
   "header_news": "News",
   "hero_tagline": "Verwandle deine <b class='green-100'>Gedanken</b> sofort in <b class='green-100'>typsichere</b> Software und <b class='green-100'>Ui</b>.",
   "initiation_authors": "invisageable & die compilords",
@@ -30,7 +31,7 @@
   "initiation_subtitle": "Eine Einführung in zo.",
   "initiation_title": "Einführung",
   "initiation_translators": "Übersetzt von ...",
-  "manifesto_content": "zo ist ein Compiler eines Compilers in einem weiteren riesigen Compiler, der selbst in einem gigantischen Compiler steckt.\n\nZiel des Projekts ist es, die Entwickler-Experience zu verbessern und das Bauen von Software, die deine <b class='green-100'>Kreativität</b> widerspiegelt, mühelos zu machen. Wir fokussieren uns auf die Details, die zählen, und öffnen neue Dimensionen im Software-Universum, in denen das Verwandeln deiner Gedanken in Programme nicht nur einfach, sondern angenehm ist.\n\nzo ist ein komplettes Ökosystem, das dir die Schlüssel in die Hand gibt. Endlich hast du die <b class='green-100'>Kontrolle</b> über deine Workstation. Du wirst nie wieder im Blindflug arbeiten müssen. Unsere Werkzeuge liefern dir alle Informationen, die du für dein Programm brauchst — von Design bis Auslieferung.\n\nWir stellen uns gegen die ausufernde Software-<b class='green-100'>Uniformität</b>. zo vereint <b class='green-100'>Web</b> und <b class='green-100'>GPU</b> — nicht indem das Web in ein Canvas gezwungen wird, sondern durch das Zusammenspiel von Flexbox-Layouts mit roher GPU-Power. Wir tun alles, um die Grenzen der Innovation auszureizen.\n\n<b class='green-100'>Schließ dich der Devolution an</b>.",
+  "manifesto_content": "Ziel des Projekts ist es, die Entwickler-Experience zu verbessern und das Bauen von Software, die deine <b class='green-100'>Kreativität</b> widerspiegelt, mühelos zu machen. Wir fokussieren uns auf die Details, die zählen, wo das Verwandeln deiner Gedanken in Programme nicht nur einfach, sondern angenehm ist.",
   "manifesto_title": "## manifest",
   "nav_benchmarks": "Benchmarks",
   "news_description": "Alles rund um zo: Releases, Meilensteine und Design-Notizen.",
@@ -50,8 +51,8 @@
   "oss_merged_prs": "zusammengeführte PRs",
   "oss_stars": "Sterne",
   "oss_title": "## oss",
-  "prologue_description": "Eine Sprache zum Ausliefern, Ausführen und Erstellen von <b class='green-100'>nativen</b> und <b class='green-100'>Web</b>-Anwendungen, optimiert auf Geschwindigkeit. zo ist ein funktionsreiches Ökosystem mit Fokus auf hohe Leistung, Einfachheit und <b class='green-100'>datenorientiertes Design</b>.",
-  "prologue_punchline": "Eine Sprache. Ein Compiler. Eine Binärdatei. <b class='green-100'>Nativ</b> oder <b class='green-100'>Web</b> — <b class='green-100'>derselbe Quellcode</b>.",
+  "prologue_description": "zo (ausgesprochen /zu:/ wie „zoo“) ist eine praktische, leichtgewichtige, plattformübergreifende und universelle Programmiersprache. Zum Ausliefern, Ausführen und Erstellen <b class='green-100'>typsicherer</b> <b class='green-100'>Desktop</b>-, <b class='green-100'>Mobile</b>- und <b class='green-100'>Web</b>-Anwendungen aus einer einzigen Codequelle.",
+  "prologue_punchline": "Eine Sprache. Ein Compiler. Eine Binärdatei. Ein Fenster. <b class='green-100'>Alle Plattformen</b> — <b class='green-100'>derselbe Quellcode</b>.",
   "prologue_title": "Die Programmiersprache zo.",
   "purpose_description": "Kreative Entwickler sollten nicht zwischen <b class='green-100'>einfachem Ui-Code</b> und <b class='green-100'>hoher Leistung</b> wählen müssen. APIs sind zerstückelt, Werkzeuge sind zu komplex, die Entwicklungsschleife ist zu langsam. Wir haben zo als den <b class='green-100'>Klebstoff</b> entwickelt — eine einzige, intuitive Sprache, mit der du deine kreativen Gedanken <b class='green-100'>sofort</b> in robuste, plattformübergreifende Software verwandelst.",
   "purpose_quote_sentence": "Warum sich mit langsamen Compilern abfinden? Macht sie einfach schneller.",

apps/site/messages/en.json

@@ -3,23 +3,24 @@
   "benchmarks_description": "Most of the compilers are <b class='green-100'>2-5x</b> slower than they could be. zo is the <b class='green-100'>fastest</b> next-gen compiler tool to enhance the programmers <b class='green-100'>productivity</b>.",
   "benchmarks_disclaimer_methodology": "<a class='link-basic' href='https://github.com/invisageable/zo/blob/main/crates/compiler/zo-benches'>@methodology-and-full-numbers</a>",
   "benchmarks_disclaimer_workload": "Workload: <b class='green-100'>10,000 lines</b> of code compiled to native <b class='green-100'>ARM64</b> binary (including Hindley-Milner type inference, monomorphization, type checking, constant folding, propagation, dead code elimination and link passes).",
-  "benchmarks_quote_sentence": "The faster your software runs, the less power his consumed.",
+  "benchmarks_quote_sentence": "The faster your software runs, the less power is consumed.",
   "benchmarks_title": "## benchmarks",
   "community_description": "A playground for compiler <b class='green-100'>nerds</b>, frontend <b class='green-100'>hackers</b>, and <b class='green-100'>creatives</b>. Open an issue, or come say hello on <a href='https://discord.gg/JaNc4Nk5xw'>Discord</a>.",
   "community_title": "## community",
-  "features_fast_content": "Built from scratch using modern compiler techniques for <b class='green-100'>instant execution</b> and rapid debugging with <b class='green-100'>helpful error messages</b>.",
+  "features_fast_content": "Built from scratch using modern compiler techniques for <b class='green-100'>instant builds</b> and rapid debugging with <b class='green-100'>helpful error messages</b>.",
   "features_fast_title": "Fast",
-  "features_integrated_content": "A complete workstation with built-in tools — package manager <sup class='superscript green-100'><a href='https://github.com/invisageable/zo/blob/main/crates/packager/fret'>fret</a></sup> and text editor <sup class='superscript green-100'><a href='https://github.com/invisageable/codelord'>codelord</a></sup>.",
+  "features_integrated_content": "A complete workstation with built-in tools — package manager <sup class='superscript green-100'><a href='https://github.com/invisageable/zo/blob/main/crates/packager/fret'>fret</a></sup> and text editor <sup class='superscript green-100'><a href='#'>codelord</a></sup>.",
   "features_integrated_title": "Integrated",
   "features_quote": "Do less work by not wasting effort.",
-  "features_safe_content": "Statically & strongly typed. Uses green and OS threads wrapped in <b class='green-100'>nursery task scopes</b>; no leaked threads, <b class='green-100'>no data races</b>.",
+  "features_safe_content": "Statically & strongly typed, with <b class='green-100'>no null</b> and no raw pointers. Green and OS threads run in <b class='green-100'>nursery task scopes</b> — no leaked threads, <b class='green-100'>no shared mutable state</b>.",
   "features_safe_title": "Safe",
   "features_title": "## features",
-  "features_unified_content": "Write Ui once with ZSX — target native <sup class='superscript green-100'>gpu</sup> or the web <sup class='superscript green-100'>dom</sup>.",
+  "features_unified_content": "Write Ui once with ZSX — target desktop <sup class='superscript green-100'>gpu</sup>, mobile <sup class='superscript green-100'>uikit</sup>, or the web <sup class='superscript green-100'>dom</sup>.",
   "features_unified_title": "Unified",
   "foundations_description": "Powered by modern and reliable foundations to deliver <b class='green-100'>high-performance</b> <b class='green-100'>graphics</b> and <b class='green-100'>web</b> integration.",
   "foundations_title": "## foundations",
   "header_initiation": "Initiation",
+  "header_spec": "Spec",
   "header_news": "News",
   "hero_tagline": "Turn your <b class='green-100'>thoughts</b> into <b class='green-100'>type-safe</b> software and <b class='green-100'>Ui</b> instantly.",
   "initiation_authors": "invisageable & the compilords",
@@ -30,7 +31,7 @@
   "initiation_subtitle": "An initiation to zo.",
   "initiation_title": "Initiation",
   "initiation_translators": "Translated by ...",
-  "manifesto_content": "zo is a compiler of a compiler inside another giant compiler that is itself inside a gigantic compiler.\n\nThe aim of the project is to enhance the developer experience, making it seamless to build software that reflects your <b class='green-100'>creativity</b>. We focus on details that matter, opening new dimensions in the software universe where transforming your thoughts into programs is not just easy, but enjoyable.\n\nzo is a complete ecosystem that gives you the keys. You finally have <b class='green-100'>control</b> over your workstation. You'll never have to work blind again. Our tools provide all the information you need for your program, from design to delivery.\n\nWe are against abundant software <b class='green-100'>uniformity</b>. zo unifies the <b class='green-100'>web</b> and the <b class='green-100'>GPU</b> — not by forcing the web into a canvas, but by harmonizing Flexbox layouts with raw GPU power. We will do everything we can to push the boundaries of innovation to the limit.\n\n<b class='green-100'>Join the devolution</b>.",
+  "manifesto_content": "The aim of the project is to enhance the developer experience, making it seamless to build software that reflects your <b class='green-100'>creativity</b>. We focus on details that matter, where transforming your thoughts into programs is not just easy, but enjoyable.",
   "manifesto_title": "## manifesto",
   "nav_benchmarks": "Benchmarks",
   "news_description": "Everything related to zo, releases, milestones and design notes.",
@@ -50,10 +51,10 @@
   "oss_merged_prs": "merged PRs",
   "oss_stars": "stars",
   "oss_title": "## oss",
-  "prologue_description": "A language to ship, run and build <b class='green-100'>native</b> and <b class='green-100'>web</b> applications optimized for speed. zo is a feature-rich ecosystem focus on high-performance, simplicity and <b class='green-100'>data-oriented</b>.",
-  "prologue_punchline": "One language. One compiler. One binary. <b class='green-100'>Native</b> or <b class='green-100'>Web</b> — <b class='green-100'>same source</b>.",
+  "prologue_description": "zo (pronounced /zu:/ just like “zoo”) is a practical, lightweight, cross-platform, general-purpose programming language. To ship, run and build <b class='green-100'>type-safe</b> <b class='green-100'>desktop</b>, <b class='green-100'>mobile</b> and <b class='green-100'>web</b> applications with one code source.",
+  "prologue_punchline": "One language. One compiler. One binary. One window. <b class='green-100'>All platforms</b> — <b class='green-100'>same source</b>.",
   "prologue_title": "The zo programming language.",
-  "purpose_description": "Creative developers shouldn't have to choose between writing <b class='green-100'>simple UI code</b> and getting <b class='green-100'>high performance</b>. APIs are disjointed, tools are overly complex, and the development loop is too slow. We built zo to be the <b class='green-100'>glue</b> — a single, intuitive language that lets you turn your creative thoughts into robust, cross-platform software <b class='green-100'>instantly</b>.",
+  "purpose_description": "Creative developers shouldn't have to choose between <b class='green-100'>simple UI code</b> and <b class='green-100'>high performance</b>. APIs are disjointed, tools are overly complex, and the development loop is too slow. We built zo to be the <b class='green-100'>glue</b> — a single, intuitive language that lets you turn your creative thoughts into robust, cross-platform software <b class='green-100'>instantly</b>.",
   "purpose_quote_sentence": "Why accept slow compilers? Just make them faster.",
   "purpose_title": "## purpose",
   "reachout_copyright": "Compilords© 2024 — present.",