Dev

CLAUDE.md

@@ -7,7 +7,7 @@ dated meeting notes (`meetings`), a BibTeX reader and `#citation` note
 constructor (`bibtex`), an endlessly scrolling presentation over notes
 (`slipshow`), a board of draggable cards for arranging notes by hand
 (`pinboard`), and venues with their calls and deadlines (`cfps`). Each package
-lives in `<name>/<version>/` (e.g. `search/0.1.0/`)
+lives in `<name>/<version>/` (e.g. `search/0.1.1/`)
 and mirrors the same layout: `typst.toml`, `src/`, and a `Justfile`, plus a
 `flake.nix` where the package pins a toolchain of its own (`search` for
 node/pnpm, `slipshow` likewise). Four of them (`search`, `todos`, `slipshow`,
@@ -137,7 +137,7 @@ packages" below) and `rheo
 compile` a test project that imports it. No per-package devShell needed
 either for most work: this repo's own root `flake.nix`/`.envrc` provide
 `just` and `typst`, and direnv finds them by walking up from anywhere under
-the repo. `search/0.1.0` and `slipshow/0.1.0` each carry their own `flake.nix`
+the repo. `search/0.1.1` and `slipshow/0.1.1` each carry their own `flake.nix`
 on top of that, for `node`/`pnpm` pinned to that package specifically.
 
 ## Pattern: consuming the injected `rheo-context`
@@ -225,7 +225,7 @@ rheo present at all.
   on this machine) — readable from package scope without any `ctx:`
   parameter.
 - `@rookery/core` uses this pattern throughout and takes NO `ctx` parameter at
-  all: see `core/0.1.0/src/lib.typ`'s `_rheo-ctx()`/`_target()` helpers.
+  all: see `core/0.1.1/src/lib.typ`'s `_rheo-ctx()`/`_target()` helpers.
 
 DO NOT assert or panic when rheo is absent under this pattern — that's
 Pattern A's job for packages that genuinely can't function without rheo.

bibtex/0.1.1/.gitignore

@@ -0,0 +1,3 @@
+.direnv/
+build
+*.pdf

bibtex/0.1.1/Justfile

@@ -0,0 +1,55 @@
+default:
+    @echo "rookery-bibtex: pure Typst package, entrypoint is src/lib.typ directly — nothing to build"
+
+# Unit fixture for the parser, the title/key derivations and the field view,
+# plus the rendered `all()` sweep fixture. No runner for the unit half:
+# `assert.eq` inside `test/units.typ` fails the compile with a line number,
+# and a passing compile is the green light — the same shape `@rookery/core`
+# and `@rookery/timeline` use. The rendered half (`test/sweep.typ`) compiles
+# to HTML and `test/check.sh` greps what came out.
+#
+# `--root .` so a fixture's `#import "/src/lib.typ"` resolves against THIS
+# package. `--features html` for parity with this repo's other Justfiles.
+# `--format pdf` with a `/dev/null` output for `units.typ` because typst
+# cannot infer a format from that path, and nothing there is rendered — only
+# asserted.
+#
+# `sweep*.typ`'s stderr is captured and grepped for `did not converge`: a
+# sweep that calls the CLAIMING `citation` from inside its own loop reads its
+# own write in the same pass, and Typst's state resolution oscillates and
+# gives up with exactly that warning while still exiting 0 — a silently
+# incomplete bibliography on a build that only warns. `all()` is built to
+# avoid it (see `src/claim.typ`), and `keywords: "existing"` reads the tag
+# registry mid-sweep for the same reason (see `src/lib.typ`) — this is what
+# would catch a regression in either: `typst compile` alone would not, since
+# the warning does not fail the build.
+#
+# `sweep-all.typ`/`sweep-existing.typ` are separate documents, not two calls
+# in `sweep.typ`, because a second `all()` call is a compile error — each
+# needs its own `bibtex(..)` and its own vertebra.
+#
+# `test/large.typ` parses a field past Typst's 10,000-iteration `while`
+# ceiling and a 400-entry corpus, so a parser that regresses to stepping
+# character by character fails the compile rather than passing unnoticed.
+test:
+    typst compile --features html --root . --format pdf test/units.typ /dev/null
+    @echo "units OK"
+    typst compile --features html --root . --format pdf test/large.typ /dev/null
+    @echo "large OK"
+    # `mkdir` first: unlike `rheo`, `typst compile` does not create its output
+    # directory and fails with "No such file or directory" on a fresh checkout,
+    # since `test/build/` is gitignored and never committed.
+    mkdir -p test/build
+    typst compile --features html --format html --root . test/sweep.typ test/build/sweep.html 2>test/build/sweep.stderr
+    cat test/build/sweep.stderr >&2
+    ! grep -q "did not converge" test/build/sweep.stderr
+    typst compile --features html --format html --root . test/sweep-existing.typ test/build/sweep-existing.html 2>test/build/sweep-existing.stderr
+    cat test/build/sweep-existing.stderr >&2
+    ! grep -q "did not converge" test/build/sweep-existing.stderr
+    typst compile --features html --format html --root . test/sweep-all.typ test/build/sweep-all.html 2>test/build/sweep-all.stderr
+    cat test/build/sweep-all.stderr >&2
+    ! grep -q "did not converge" test/build/sweep-all.stderr
+    typst compile --features html --format html --root . test/fields.typ test/build/fields.html 2>test/build/fields.stderr
+    cat test/build/fields.stderr >&2
+    ! grep -q "did not converge" test/build/fields.stderr
+    ./test/check.sh

bibtex/0.1.1/demo/rheo/Justfile

@@ -0,0 +1,10 @@
+# rheo is NOT in this repo's devShell — locally it is the sibling `rheo/`
+# crate, same as `@rookery/core`'s own demo (see that Justfile's header).
+build:
+    rheo compile .
+
+watch:
+    rheo watch . --html --open
+
+clean:
+    rm -rf build

bibtex/0.1.1/demo/rheo/content/entry.typ

@@ -0,0 +1,16 @@
+// The hand-written half of the bibliography: this note's body is authored,
+// not swept — `index.typ`'s `all()` mints every OTHER entry with the empty
+// body a swept note always gets. A hand-written `#citation` for a key always
+// wins over `all()`, no matter where the two calls sit relative to each
+// other.
+#import "lib.typ": demo, refs
+
+#show: demo
+
+= A cited entry
+
+#(refs.citation)("okafor2019")[
+  Cited directly, because its accounting of responsiveness as a budget spent
+  reframes what the rest of this bibliography treats as measured only after
+  the fact.
+]

bibtex/0.1.1/demo/rheo/content/index.typ

@@ -0,0 +1,11 @@
+// The rest of the bibliography, swept in one call: `all()` mints a note for
+// every entry `entry.typ`'s hand-written `#citation` has not already
+// claimed — see `@rookery/bibtex`'s readme, "all() — minting the rest of the
+// bibliography".
+#import "lib.typ": demo, refs
+
+#show: demo
+
+= References
+
+#(refs.all)()

bibtex/0.1.1/demo/rheo/content/lib.typ

@@ -0,0 +1,30 @@
+// The one place the demo is configured, applied by both vertebrae — same
+// reason `@rookery/core`'s own demo does this (see its `content/lib.typ`):
+// `#show: rookery` is per-FILE, so a project that wants one configuration
+// wraps it once here and every vertebra applies the wrapper.
+#import "@rookery/core:0.1.1": rookery
+#import "@rookery/bibtex:0.1.1": bibtex
+
+#let refs = bibtex(read("../references.bib"))
+
+// Appended after every minted page's OWN body — `entry.typ`'s hand-written
+// citation as much as every entry `index.typ`'s `all()` sweeps — so a reader
+// lands on the bibliographic record regardless of which path minted the
+// page. A NAMED TOP-LEVEL FUNCTION, deliberately: `idea-page-template` is
+// read back from document-wide state, so an inline closure built inside
+// `demo` below would be a different value per vertebra and whichever file
+// happened to compile last would win.
+// `id` arrives prefixed (`idea:<key>`, the default `prefix:` `#show: rookery`
+// publishes) — the bare BibTeX key, which is what `refs.fields` looks up, is
+// everything after the first `:`.
+#let citation-page(id: none, note: (:), doc) = {
+  doc
+  if id != none {
+    (refs.fields)(id.split(":").last())
+  }
+}
+
+#let demo(doc) = {
+  show: rookery.with(idea-page-template: citation-page)
+  doc
+}

bibtex/0.1.1/demo/rheo/references.bib

@@ -0,0 +1,38 @@
+@book{harrow2014,
+  title = {Assembling the Archive: Notes Toward a Practice},
+  shorttitle = {Assembling the Archive},
+  author = {Harrow, Elena},
+  year = {2014},
+  publisher = {Tidewater Press},
+}
+
+@article{okafor2019,
+  title = {Latency Budgets for Interactive Systems},
+  author = {Okafor, Chidi},
+  journal = {Journal of Systems Research},
+  volume = {12},
+  pages = {201--227},
+  year = {2019},
+  doi = {10.5555/jsr.2019.0012},
+  abstract = {Argues that a system's perceived responsiveness is a budget spent, not a property measured after the fact, and proposes a way to account for it at design time.},
+}
+
+@inproceedings{singh2021,
+  title = {Incremental Computation for Editable Documents},
+  author = {Singh, Priya and Novak, Tomas and Reyes, Marisol},
+  booktitle = {Proceedings of the Workshop on Live Systems},
+  year = {2021},
+}
+
+@book{fenwick2017,
+  title = {Field Notes on Distributed Consensus},
+  editor = {Fenwick, Dorothy},
+  year = {2017},
+  publisher = {Causeway Editions},
+}
+
+@misc{fielding2022,
+  title = {Notes on a Small Protocol},
+  author = {Fielding, Sam},
+  year = {2022},
+}

bibtex/0.1.1/demo/rheo/rheo.toml

@@ -0,0 +1,20 @@
+# @rookery/bibtex's in-repo demo: a small rookery whose notes come from
+# `references.bib` rather than hand-authored prose — `content/index.typ`
+# sweeps the whole bibliography with `all()`, `content/entry.typ` claims one
+# entry by hand with `#citation` to show the override `all()` respects.
+version = "0.6.2"
+content_dir = "content"
+formats = ["html"]
+
+# `lib.typ` is a library, not a page: it holds the shared `#show: rookery`
+# wrapper both vertebrae apply. Without this it would compile to its own
+# `lib.html`.
+[spine]
+exclude = ["lib.typ"]
+
+# The Typst cache's `rookery` namespace is a per-machine symlink that can
+# point at a different checkout of this repo, so this reads `@rookery/*` out
+# of this tree instead. See `slipshow/0.1.1/demo/rheo/rheo.toml` for the full
+# argument.
+[packages.rookery]
+path = "../../../.."