feat: make typst fonts more hermetic

MODULE.bazel

@@ -2,7 +2,7 @@
 
 module(
     name = "rules_typst",
-    version = "0.2.0",
+    version = "0.3.0",
 )
 
 bazel_dep(name = "rules_rust", version = "0.68.1")

README.md

@@ -2,6 +2,43 @@
 
 Bazel rules for [Typst](https://typst.app/).
 
+## Reproducibility
+
+Compilation sees only the declared inputs, so the same sources produce the same
+PDF bytes on every machine:
+
+- `SOURCE_DATE_EPOCH=0` fixes the document's creation timestamp. Override it
+  through the `env` attribute to opt out.
+- Fonts installed on the host are ignored. Only the fonts embedded in the pinned
+  compiler are available.
+- The package path and package cache point inside the action, so a `@preview`
+  import cannot resolve against a developer's `~/.cache/typst`.
+
+Fonts are the usual source of "works on my machine": a document that renders
+with a system font produces a different glyph subset — and therefore different
+bytes — wherever that font's build differs. Typst reports an unknown font family
+as a warning and silently falls back to a default, so check the build log if the
+output is not what you expect.
+
+Hermetic font handling requires Typst 0.12 or newer, when
+`--ignore-system-fonts` was added.
+
+## Checking in generated PDFs
+
+`write_source_file` runs `diff` when its test fails, which prints thousands of
+lines of xref offsets and compressed font streams for a PDF. Pass `--brief` so
+the log reports only that the file changed:
+
+```python
+write_source_file(
+    name = "write_report_pdf",
+    diff_args = ["--brief"],
+    diff_test = True,
+    in_file = ":report",
+    out_file = "generated/report.pdf",
+)
+```
+
 ## Development
 
 ### Pre-commit hooks

examples/BUILD.bazel

@@ -47,6 +47,9 @@ typst(
 
 write_source_file(
     name = "write_example_pdf",
+    # A PDF is binary, so report only whether it changed rather than dumping
+    # xref tables and font streams into the test log.
+    diff_args = ["--brief"],
     diff_test = True,
     in_file = ":example",
     out_file = "generated/source_sync/example.pdf",