Developing Animo¶
This guide is for someone who wants to change Animo itself. To write a deck with Animo, read the Presentation Author Guide and the Reference instead.
| Page | Covers |
|---|---|
| Development Environment | setting up a clone, the uv environment, the two import paths, commands |
| Testing | the three test tiers, the browser engines, continuous integration |
| The Browser Runtime | the page structure, the runtime files, the controller and its events |
| Behaviour Probes | what a probe asserts, how to add one, and what to do when one fails |
| Generative AI Disclaimer | why much of Animo was written with the help of generative AI |
Repository Layout¶
| Directory | Holds | Covered by |
|---|---|---|
src/ |
the typst package, with lib.typ as its entry point |
the design document |
src/js/ |
the browser runtime, which src/deck.typ joins into the HTML output |
The Browser Runtime |
tests/ |
the feature tests, and the test harness under tests/harness/ |
Testing |
probes/ |
one probe module per entry in Findings, or per group of entries | Behaviour Probes |
demos/ |
the demo decks that the Presentation Author Guide draws on | The Documentation Site |
docs/ |
the pages of this site | The Documentation Site |
planning/ |
the design document and Findings | Where the Specification Lives |
tools/ |
scripts that build the demo decks and the package, and check the package | Continuous Integration |
benchmarks/ |
the benchmark script, its documents and the committed results | Benchmarks |
logo/ |
the logos, and the source of the social cards | The Documentation Site |
.typst-packages/ |
the symlink that resolves @preview/animo:0.2.0 to the working tree |
The Two Import Paths |
Where the Specification Lives¶
This site does not include the specification.
The specification consists of two documents in the planning/ directory of the
repository.
planning/design.md,
the design document, specifies how Animo works
and is the reference for any change in behaviour.
Read it before changing anything under src/.
Two of its sections carry more weight than the rest.
Resolved Design Decisions records questions that are settled, and why.
Open Questions records what is deliberately undecided.
planning/findings.md,
referred to as Findings,
records verified behaviour of typst and of the browsers that Animo drives.
The design of Animo depends on each of these behaviours, and each was expensive to establish.
Every entry in Findings therefore has a probe under probes/,
which asserts the behaviour itself rather than a feature that happens to depend on it.
See Behaviour Probes for how the probes work.
Planned work is tracked as issues and pull requests on GitHub.
The other pages of this site refer to these documents as "the design document" and Findings. A page that relies on a specific finding quotes the heading of its entry in prose, as in "Findings records that the document timeline is not a clock". To read the entry, search Findings for that heading. The pages do not link to the heading, because the documentation build does not check links into GitHub, so such a link would break unnoticed when the heading is renamed.
Contributing¶
Describe a change in behaviour in the design document before implementing it. When an observation about typst or a browser was expensive to make, record it in Findings and add a probe that asserts it.
See CONTRIBUTING.md for the conventions and for the commands to run before opening a pull request.