Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
c8a3180
docs(interpreters): center delegation on composition
tgrospic Aug 19, 2026
1607d85
docs(expression-problem): compare Featherweight Go with DD
tgrospic Oct 1, 2026
e7e0aff
Build local enchanted ALUX programming book experience
shixi-11 Oct 22, 2026
dc5eb68
Complete multilingual dual-world reading experience
shixi-11 Oct 22, 2026
85516c6
Refresh forest entrance and multilingual share previews
shixi-11 Oct 22, 2026
796fe1f
Polish multilingual readers and add localized welcome audio
shixi-11 Oct 22, 2026
b70b759
Refine bilingual previews and make audio controls immediate
shixi-11 Oct 23, 2026
ff31e40
Polish reader hierarchy, search, music hints and day materials
shixi-11 Oct 23, 2026
1b785ee
Unify book and scroll presentation and refresh multilingual introduct…
shixi-11 Oct 23, 2026
050eef1
Fix contents actions and use continuous book pagination
shixi-11 Oct 23, 2026
efbd7a6
Navigate chapter endings to a full contents page
shixi-11 Oct 23, 2026
187a37b
Refresh reader previews and multilingual book introductions
shixi-11 Oct 23, 2026
58ed536
Align localized sharing cards and GitHub introductions
shixi-11 Oct 23, 2026
82e036d
Build typed readers from native mdBook content
shixi-11 Oct 23, 2026
6ae6444
Keep stale reader tasks from removing new chapter pages
shixi-11 Oct 23, 2026
2e54da9
Show readable pages during loading and right-size web artwork
shixi-11 Oct 23, 2026
0ac51cc
Refresh tab icon and use Chinese and English site identities
shixi-11 Oct 23, 2026
87442d8
Reduce repeated reader search and pagination work
shixi-11 Oct 23, 2026
8d1397b
Document consistent browser titles and site identity checks
shixi-11 Oct 23, 2026
9df15cc
Refine browser icon materials and increase logo breathing room
shixi-11 Oct 23, 2026
ac70ab9
Refactor multilingual readers around source Markdown and Solid state
shixi-11 Oct 26, 2026
aca4f04
Unify reactive language state and validate protected media attributes
shixi-11 Oct 26, 2026
ba2274d
Record migration evidence and independent review resolutions
shixi-11 Oct 26, 2026
6e731f5
Fix on-demand pagination and reader lifecycle acceptance
shixi-11 Oct 26, 2026
e40f09b
Close lifecycle review findings and record browser acceptance
shixi-11 Oct 26, 2026
3c8c4e9
Keep embedded players out of navigation snapshots
shixi-11 Oct 26, 2026
9857efb
Pin reader CI runner and bound acceptance runtime
shixi-11 Oct 26, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
48 changes: 48 additions & 0 deletions .github/workflows/reader.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
name: Reader acceptance
on:
pull_request:
branches: [master]
push:
branches: [master]
permissions:
contents: read
jobs:
reader:
runs-on: ubuntu-24.04
timeout-minutes: 30
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '24'
- uses: pnpm/action-setup@v4
with:
version: 11.25.0
- uses: ./.github/actions/setup-rust
- name: Install pinned mdBook tools
run: |
cargo install mdbook --version 0.4.52 --locked
cargo install mdbook-admonish --version 1.20.0 --locked
cargo install mdbook-katex --version 0.9.4 --locked
- name: Frozen dependencies and compiler lint
working-directory: web
run: |
pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
- name: Build, unit tests, generated links and repeatability
working-directory: web
run: |
pnpm build
pnpm test:generated
cp ../output/merge-acceptance/generated-inventory.json /tmp/reader-inventory.json
pnpm test
pnpm build
pnpm test:generated
cmp /tmp/reader-inventory.json ../output/merge-acceptance/generated-inventory.json
- name: Desktop engines and mobile profile simulations
working-directory: web
run: |
pnpm exec playwright install --with-deps chromium firefox webkit
pnpm test:browser
pnpm test:acceptance
7 changes: 7 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1 +1,8 @@
book
output/
web/node_modules/
web/dist/
web/.cache/
web/public/content.json
web/public/content/
web/public/book-assets/
25 changes: 25 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Maintaining ALUX Programming

This repository contains the original mdBook in `src/` and a multilingual reader in `web/`. Read [web/AGENTS.md](web/AGENTS.md) before changing reader content, typography, artwork, language routing or controls. It defines alignment, type sizes, capitalization, responsive behavior and the checks required after a change.

- Keep the book's meaning, author attribution, equations, code, heading anchors and existing source links intact. Use semantic Markdown heading levels. Register new chapters in `src/SUMMARY.md`.
- Do not edit `web/public/content.json`, localized `web/public/content/`, copied `web/public/book-assets/` files or `web/dist/` by hand. Generate them with the existing scripts.
- The two magic reading modes share their type scale in `web/reader-presentation.css`. A fix must cover both `.folio-content` and `.continuous-prose`. Check the real reader separately.
- The web illustration mapping lives in `web/scripts/reader-presentation.ts`; see [web/ARTWORK.md](web/ARTWORK.md) for source and runtime assets. Retain original mdBook illustrations unless the task explicitly changes those sources.
- Keep the root English README and `docs/README.<language>.md` language introductions consistent. Use language names, relative links and a clear active-language marker. GitHub README links do not perform the website's automatic language selection.
- Keep public introductions concise and factual. Do not insert internal production notes, unverified deployment claims or private correspondence into the reader or README.
- Preserve mdBook as the content compiler. The typed JSON backend owns chapter structure; the native HTML renderer owns Markdown, preprocessors and canonical anchors. The shared model and localization live in `web/src/`; reader-specific code handles presentation and interaction only. Do not restore a second Markdown compiler or manual SUMMARY parser.
- Translations belong beside canonical chapters as `chapter.<lang>.md`, selected by the web-only mdBook preprocessor. Keep one SUMMARY and stable chapter/heading identities, with English fallback for missing files. UI messages belong in `web/locales/ui/`; never restore prose dictionaries, token alignment or runtime DOM translation. Solid components own app state; imperative code is limited to opaque content, layout/animation and browser media adapters. Read `web/docs/source-localization-migration.md` before revising this boundary.
- Run `pnpm --dir web build`, `pnpm --dir web test` and the checks relevant to the changed behavior. Shared presentation changes require day/night, book/scroll, desktop/tablet/phone and all supported languages, including RTL. Inspect rendered pages as well as computed values.
- Follow the user's current branch and PR scope. Preserve unrelated changes; do not merge, enable auto-merge, deploy, change licensing or replace the publishing workflow without authorization.

## Measurable acceptance, not another rewrite

Follow [the merge acceptance ledger](web/docs/merge-acceptance.md) and [Tomislav's acceptance review](https://github.com/alux-network/alux-programming/pull/2#issuecomment-6420843360). Fix reproducible blockers; do not reopen the accepted architecture or redesign the readers.

- Opening a chapter measures only its own layout resources. Do not paginate unseen chapters, even in background work, to obtain a global total. The owner selected explicitly labelled chapter progress until reliable exact-layout counts are available from real visits.
- Verify lifecycle cleanup and interrupted page turns with repeated browser scenarios; source inspection or one final screenshot is insufficient.
- English edits warn about potentially stale translations. Builds never silently mark translations reviewed or update their fingerprints.
- Verify a fresh tracked checkout with frozen installation, strict types, compiler lint, build/tests, deterministic repeated generated output and resolved links/anchors/assets. Add frontend CI without replacing original publishing.
- Mark each criterion **PASS / FAIL / NOT TESTED**, with command, actual engine/browser version and evidence. Mobile-profile Chromium/WebKit are simulations, not physical Android/iOS results. The owner has Android but no iPhone/iPad.
- Update this guide, `web/AGENTS.md` and the ledger together. Record remaining merge gates; local success is not authorization to merge or enable auto-merge.
39 changes: 29 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,38 @@
# <img src="src/assets/alux-logo.png" style="margin-right: 10px; width: 60px;"> ALUX programming guidelines
# ALUX Programming

A book about **designing programs by meaning first** — specifying *what* a program means before deciding *how* it runs — in the style of Conal Elliott's Denotational Design, with a concrete path into Rust.
**English** · [简体中文](docs/README.zh.md) · [繁體中文](docs/README.zh-hant.md) · [日本語](docs/README.ja.md) · [한국어](docs/README.ko.md) · [Tiếng Việt](docs/README.vi.md) · [Deutsch](docs/README.de.md) · [Español](docs/README.es.md) · [Русский](docs/README.ru.md) · [Українська](docs/README.uk.md) · [العربية](docs/README.ar.md)

It provides the foundation for understanding and contributing to ALUX’s meaning-first codebase.
![ALUX Programming](web/public/social/alux-programming-en.jpg)

Built with [mdBook] and published to GitHub Pages: <https://alux-network.github.io/alux-programming/>
A book about designing programs by first defining their meaning, then choosing how to execute them. It follows Conal Elliott’s denotational design approach through composition, laws and interpreters, with examples in Rust.

## What's inside
The book provides the foundation for understanding and contributing to ALUX’s meaning-first codebase. Written by Tomislav Grospic.

The book is organized in four parts (full table of contents in [`src/SUMMARY.md`](src/SUMMARY.md)):
[Read online](https://alux-network.github.io/alux-programming/) · [Contents](src/SUMMARY.md) · [Web reader setup](web/README.md)

- **The Semantic View** — denotations, compositionality, laws and interpretations, dependent types: the meaning-first foundation.
- **Design by Meaning in Rust** — capability algebras, derived meaning and composition, interpreters and effects, laws/scenarios/evidence, first-order programs, compiler pipelines, and a meaning-first workflow.
- **Concepts** — operational semantics, the expression problem, referential transparency, free monads, continuation-passing style, defunctionalization, branching and confluence.
- **Insights** — short essays connecting those concepts back to the semantic view (semantics to machines, the expression problem reloaded, referential transparency reloaded, and the EVM as an algebra).
## In the book

- **The Semantic View** — denotations, compositionality, laws, interpretations and dependent types.
- **Design by Meaning in Rust** — capability traits, derived operations, interpreters, evidence and compiler pipelines.
- **Concepts** — operational semantics, free monads, continuations, defunctionalization and related mechanisms.
- **Insights** — connections between those mechanisms, program meaning and execution.

## Multilingual web reader

The web reader offers eleven languages, a paper book view and continuous scrolling, plus a plain technical view. A full contents page opens chapters directly. Book-view page numbers continue across chapters and adjust to the language, text size and window. Both worlds share font size, day/night mode, search and bookmarks.

[Telegram and X preview](web/previews/social.html) · [Preview the reader](web/previews/index.html) · [Preview screenshots](web/previews/assets/) · [Reader maintenance guide](web/AGENTS.md)

The preview HTML opens locally after checkout; its reader links require the local server below. The published online edition still uses mdBook.

Requires Node.js 22+ and pnpm:

```sh
pnpm --dir web install
pnpm --dir web dev
```

Open [127.0.0.1:4173](http://127.0.0.1:4173/). The reader selects an initial language and remembers a manual choice; all language editions remain available in the language menu. See [the maintenance guide](web/AGENTS.md) before adding content or changing the interface.

## Build and run locally

Expand Down
37 changes: 37 additions & 0 deletions docs/README.ar.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
[English](../README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-hant.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Tiếng Việt](README.vi.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Русский](README.ru.md) · [Українська](README.uk.md) · **العربية**

<div dir="rtl">

# دليل البرمجة في ALUX

![دليل البرمجة في ALUX](../web/public/social/alux-programming-ar.jpg)

يشرح هذا الكتاب كيف نحدد معنى البرنامج أولًا، ثم نختار طريقة تنفيذه. يستند إلى التصميم الدلالي لدى Conal Elliott، ويربط التركيب والقوانين والمفسرات بسمات القدرات وأمثلة بلغة Rust.

المؤلف: Tomislav Grospic.

## محتويات الكتاب

- الرؤية الدلالية: الدلالات والتركيبية والقوانين والتفسيرات والأنواع التابعة.
- التصميم بالمعنى في Rust: القدرات والعمليات المشتقة والمفسرات والأدلة وخطوط عمل المترجم.
- المفاهيم: الدلالات التشغيلية والمونادات الحرة والاستمراريات وإزالة الدوال والآليات المرتبطة بها.
- رؤى: صلة هذه الآليات بمعنى البرنامج وتنفيذه.

## القراءة

يدعم قارئ الويب إحدى عشرة لغة. يمكنك الاختيار بين تقليب الصفحات والتمرير المتصل وواجهة تقنية بسيطة، مع التحكم في حجم الخط والوضع الفاتح أو الداكن والبحث والإشارات المرجعية. يُحفظ اختيار اللغة اليدوي.

يفتح الفهرس الكامل الفصول مباشرة. يستمر ترقيم الصفحات عبر الفصول ويُعاد حسابه عند تغيير اللغة أو حجم الخط أو النافذة.

[فهرس النص الأصلي](../src/SUMMARY.md) · [Telegram / X](../web/previews/social.html) · [دليل الصيانة والتنسيق](../web/AGENTS.md)

## التشغيل محليًا

</div>

```sh
pnpm --dir web install
pnpm --dir web dev
```

[فتح النسخة العربية](http://127.0.0.1:4173/ar/)
33 changes: 33 additions & 0 deletions docs/README.de.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
[English](../README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-hant.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Tiếng Việt](README.vi.md) · **Deutsch** · [Español](README.es.md) · [Русский](README.ru.md) · [Українська](README.uk.md) · [العربية](README.ar.md)

# ALUX-Programmierleitfaden

![ALUX-Programmierleitfaden](../web/public/social/alux-programming-de.jpg)

Dieses Buch beschreibt, wie man zuerst die Bedeutung eines Programms festlegt und danach seine Ausführung wählt. Es folgt Conal Elliotts denotationellem Entwurf und verbindet Komposition, Gesetze und Interpreter mit Capability-Traits und Beispielen in Rust.

Autor: Tomislav Grospic.

## Inhalt

- Die semantische Sicht: Denotationen, Kompositionalität, Gesetze, Interpretationen und abhängige Typen.
- Entwurf nach Bedeutung in Rust: Capabilities, abgeleitete Operationen, Interpreter, Nachweise und Compiler-Pipelines.
- Konzepte: operationelle Semantik, freie Monaden, Fortsetzungen, Defunktionalisierung und verwandte Mechanismen.
- Einsichten: die Verbindung dieser Mechanismen mit Programmbedeutung und Ausführung.

## Lesen

Der Webreader unterstützt elf Sprachen. Zur Wahl stehen eine Buchansicht mit Seitenwechseln, fortlaufendes Scrollen und eine schlichte technische Ansicht. Schriftgröße, Tag-/Nachtmodus, Suche und Lesezeichen sind verfügbar. Eine manuell gewählte Sprache bleibt gespeichert.

Das vollständige Inhaltsverzeichnis öffnet Kapitel direkt. Die Seitenzahlen laufen über Kapitelgrenzen hinweg und werden bei Änderungen von Sprache, Schriftgröße oder Fenstergröße neu berechnet.

[Original-Inhaltsverzeichnis](../src/SUMMARY.md) · [Telegram / X](../web/previews/social.html) · [Wartungs- und Typografierichtlinien](../web/AGENTS.md)

## Lokal starten

```sh
pnpm --dir web install
pnpm --dir web dev
```

[Deutschen Reader öffnen](http://127.0.0.1:4173/de/)
33 changes: 33 additions & 0 deletions docs/README.es.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
[English](../README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-hant.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Tiếng Việt](README.vi.md) · [Deutsch](README.de.md) · **Español** · [Русский](README.ru.md) · [Українська](README.uk.md) · [العربية](README.ar.md)

# Guía de programación de ALUX

![Guía de programación de ALUX](../web/public/social/alux-programming-es.jpg)

Este libro explica cómo definir primero el significado de un programa y elegir después cómo ejecutarlo. Sigue el diseño denotacional de Conal Elliott y lleva la composición, las leyes y los intérpretes a ejemplos en Rust mediante traits de capacidades.

Autor: Tomislav Grospic.

## Contenido

- La perspectiva semántica: denotaciones, composicionalidad, leyes, interpretaciones y tipos dependientes.
- Diseño por significado en Rust: capacidades, operaciones derivadas, intérpretes, evidencias y procesos de compilación.
- Conceptos: semántica operacional, mónadas libres, continuaciones, desfuncionalización y mecanismos relacionados.
- Reflexiones: la relación de estos mecanismos con el significado y la ejecución de los programas.

## Leer

El lector web admite once idiomas. Permite elegir entre páginas de libro, desplazamiento continuo y una vista técnica sencilla. Incluye tamaño de letra, modo claro/oscuro, búsqueda y marcadores. La elección manual del idioma se conserva.

El índice completo abre cada capítulo directamente. La numeración continúa entre capítulos y se recalcula según el idioma, el tamaño de letra y la ventana.

[Índice original](../src/SUMMARY.md) · [Telegram / X](../web/previews/social.html) · [Normas de mantenimiento y tipografía](../web/AGENTS.md)

## Ejecutar en local

```sh
pnpm --dir web install
pnpm --dir web dev
```

[Abrir el lector en español](http://127.0.0.1:4173/es/)
33 changes: 33 additions & 0 deletions docs/README.ja.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
[English](../README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-hant.md) · **日本語** · [한국어](README.ko.md) · [Tiếng Việt](README.vi.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Русский](README.ru.md) · [Українська](README.uk.md) · [العربية](README.ar.md)

# ALUX プログラミングガイド

![ALUX プログラミングガイド](../web/public/social/alux-programming-ja.jpg)

プログラムが何を意味するかを定めてから、どう実行するかを選ぶための本です。Conal Elliott の指示的設計をもとに、合成、法則、インタープリターを説明し、Rust のケイパビリティ trait と具体例で実装につなげます。

著者:Tomislav Grospic。

## 本書の内容

- 意味論的な視点:指示、合成性、法則、解釈、依存型。
- Rust における意味による設計:ケイパビリティ、導出された操作、インタープリター、根拠、コンパイラーパイプライン。
- 概念:操作的意味論、自由モナド、継続、非関数化などの仕組み。
- 考察:それらの仕組みと、プログラムの意味や実行との関係。

## 読む

ウェブ版は11言語に対応しています。ページをめくる表示、スクロール表示、簡潔な技術文書の表示を選べます。文字サイズ、昼夜モード、検索、ブックマークを利用でき、手動で選んだ言語は次回も維持されます。

全体の目次から各章を直接開けます。ページ番号は章をまたいで続き、言語、文字サイズ、ウィンドウの大きさに応じて再計算されます。

[原文の目次](../src/SUMMARY.md) · [Telegram / X](../web/previews/social.html) · [保守・組版ガイド](../web/AGENTS.md)

## ローカルで起動

```sh
pnpm --dir web install
pnpm --dir web dev
```

[日本語版を開く](http://127.0.0.1:4173/ja/)
33 changes: 33 additions & 0 deletions docs/README.ko.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
[English](../README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-hant.md) · [日本語](README.ja.md) · **한국어** · [Tiếng Việt](README.vi.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Русский](README.ru.md) · [Українська](README.uk.md) · [العربية](README.ar.md)

# ALUX 프로그래밍 가이드

![ALUX 프로그래밍 가이드](../web/public/social/alux-programming-ko.jpg)

프로그램이 무엇을 의미하는지 먼저 정의하고, 실행 방법은 그다음에 선택하는 설계를 다룹니다. Conal Elliott의 지시적 설계를 바탕으로 합성, 법칙, 해석기를 설명하고 Rust의 능력 trait와 예제를 통해 구현으로 이어갑니다.

저자: Tomislav Grospic.

## 책의 구성

- 의미론적 관점: 지시, 합성성, 법칙, 해석, 의존 타입.
- Rust에서 의미로 설계하기: 능력, 파생 연산, 해석기, 증거, 컴파일러 파이프라인.
- 개념: 연산 의미론, 자유 모나드, 연속, 비함수화 등의 메커니즘.
- 통찰: 이러한 메커니즘과 프로그램의 의미 및 실행 사이의 관계.

## 읽기

웹 리더는 11개 언어를 지원합니다. 책장 넘기기, 스크롤, 간결한 기술 문서 보기 중에서 선택할 수 있습니다. 글자 크기, 주야간 모드, 검색, 책갈피를 제공하며 직접 선택한 언어를 기억합니다.

전체 목차에서 각 장을 바로 열 수 있습니다. 페이지 번호는 장이 바뀌어도 이어지며 언어, 글자 크기, 창 크기에 따라 다시 계산됩니다.

[원문 목차](../src/SUMMARY.md) · [Telegram / X](../web/previews/social.html) · [유지보수 및 조판 지침](../web/AGENTS.md)

## 로컬 실행

```sh
pnpm --dir web install
pnpm --dir web dev
```

[한국어 리더 열기](http://127.0.0.1:4173/ko/)
Loading
Loading