demolab-cli 2.2.1__tar.gz → 2.4.0__tar.gz

{demolab_cli-2.2.1 → demolab_cli-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: demolab-cli
-Version: 2.2.1
+Version: 2.4.0
 Summary: Lab notebook for computational science: Python tools produce per-run artifacts; Typst publishes them as a web bundle, per-entry PDFs, and a book.
 Project-URL: Homepage, https://github.com/eoinmurray/demolab
 Project-URL: Changelog, https://github.com/eoinmurray/demolab/blob/main/demolab_cli/CHANGELOG.md

{demolab_cli-2.2.1 → demolab_cli-2.4.0}/demolab_cli/CHANGELOG.md

@@ -13,6 +13,24 @@ the runbook shows the entries between your version and the latest.
 
 ## [Unreleased]
 
+## [2.4.0] — 2026-08-14
+
+### Added
+- **Collection articles can opt into a developer-documentation web theme.** Add `theme: docs`
+  to a collection in `demolab.yaml`; its article pages receive a technical sans/mono type system,
+  linked table-of-contents support, code and API-reference surfaces, and documentation-oriented
+  tables. Collection listings, experiments, PDFs, and the combined book retain the standard lab
+  presentation. The shipped demo includes a fictional Python SDK guide and API reference as a
+  complete worked example.
+
+## [2.3.0] — 2026-08-07
+
+### Added
+- **Optional collaborative inline annotations with Hypothesis.** Set `annotations: hypothesis`
+  lab-wide in `demolab.yaml` or `annotations: "hypothesis"` on one writing's `meta`; web readers
+  can highlight text and use Hypothesis threads and private groups, while PDFs remain unchanged.
+  The new `ar027` demo article documents the workflow and opts itself in as a live example.
+
 ## [2.2.1] — 2026-08-07
 
 ### Fixed

demolab_cli-2.4.0/demolab_cli/VERSION

@@ -0,0 +1 @@
+2.4.0

{demolab_cli-2.2.1 → demolab_cli-2.4.0}/demolab_cli/guides/GLOSSARY.md

@@ -10,13 +10,13 @@ RULES' `§N.M`) and listed alphabetically. Section references like `§4.3` point
 
 **G3 — Black box.** The installed `demolab-cli` package (the build engine, runbooks, guides, scaffold) plus the machine-managed `.demolab/` staging dir it materialises at the lab root. Pure upstream, never hand-edited; *"update demolab"* is a dependency bump (§3.1). Your customisation lives *outside* it, in `demolab.yaml` and your content.
 
-**G4 — Brand config.** The optional root `demolab.yaml`: wordmark, PDF titles, and the collection registry. Absent ⇒ engine defaults (§3.3, §6.5).
+**G4 — Brand config.** The optional root `demolab.yaml`: wordmark, PDF titles, and the collection registry (including optional web themes). Absent ⇒ engine defaults (§3.3, §6.5).
 
 **G5 — Bundle.** The Typst multi-document output from one compile: the site, per-entry PDFs, and the book, all emitted together by `main.typ` (§5.2).
 
 **G6 — Coding agent.** The AI assistant (Claude Code, Cursor, aider, …) that reads this repo and operates it: runs the toolchain, wires files, follows runbooks.
 
-**G7 — Collection.** A group of entries sharing a `collection:` slug in their `meta`. Entries are grouped by collection on the homepage; a slug title-cases by default, and `demolab.yaml` can give it a label/description/order (§6.5).
+**G7 — Collection.** A group of entries sharing a `collection:` slug in their `meta`. Entries are grouped by collection on the homepage; a slug title-cases by default, and `demolab.yaml` can give it a label/description/order plus an optional article web theme (§6.5).
 
 **G8 — Contract.** The file-based interface between a tool and an experiment: a tool writes a fixed set of files (§4.3), a runner reads them by running the tool's CLI (§4.5). It's language-neutral (§1.4).
 

{demolab_cli-2.2.1 → demolab_cli-2.4.0}/demolab_cli/guides/RULES.md

@@ -31,7 +31,7 @@ The concrete annotated file tree is in [`STRUCTURE.md`](STRUCTURE.md); this sect
 
 **3.2 — Machine-managed staging** (gitignored, owned by the CLI — never hand-edit): `.demolab/` at the lab root holds the few engine files Typst must read from inside the lab tree (`lib.typ`, the web assets, a `VERSION` stamp); every build refreshes it when the installed engine version changes. `temp/bundle/` holds the staged bundle root (`main.typ`) plus build scratch. Local edits to either are overwritten without warning — a customisation that seems to need them is a missing config knob (see 3.3, or propose it upstream).
 
-**3.3 — Your root overrides, optional** (root files the framework reads; never overwritten by updates): `demolab.yaml` (wordmark + PDF titles + collections — also the **lab marker**: the CLI finds the lab root by walking up to it, so don't delete it) and `HOUSESTYLE.local.md` (your house-style overrides, which extend or replace the default `HOUSESTYLE.md`; an agent reads it). Every key defaults ⇒ a minimal file is fine. The root stubs (`AGENTS.md`, `CLAUDE.md`, `README.md`, `pyproject.toml`, `.gitignore`, CI) are laid down once by `demolab init` and are yours from then on.
+**3.3 — Your root overrides, optional** (root files the framework reads; never overwritten by updates): `demolab.yaml` (wordmark + PDF titles + collections + optional web annotations — also the **lab marker**: the CLI finds the lab root by walking up to it, so don't delete it) and `HOUSESTYLE.local.md` (your house-style overrides, which extend or replace the default `HOUSESTYLE.md`; an agent reads it). Every key defaults ⇒ a minimal file is fine. The root stubs (`AGENTS.md`, `CLAUDE.md`, `README.md`, `pyproject.toml`, `.gitignore`, CI) are laid down once by `demolab init` and are yours from then on.
 
 **3.4 — User content** (100% the user's — freely deletable and replaceable): `tools/*`, `experiments/*` (runners, plus `playground.py` — the Streamlit demo, exempt from the contract), `writings/*` (`.typ` writeups), `artifacts/*` (`data/` per-run figures + `numbers.json`, `pdfs/` compiled PDFs; `artifacts/site/` is a gitignored build), `temp/*` (regenerable scratch).
 
@@ -109,6 +109,19 @@ Numbers must come from the run (§5.4) — never hand-type a literal that could
 
 **6.5a — Curated reading order.** An optional integer `order:` in a writing's `meta` marks its collection as *curated*: that collection's page lists entries by `order` ascending (unranked entries trail, in id order) instead of the default status-then-newest sort. Use it when a collection should read as a sequence — a documentation arc, a course, a serial — and leave it off for a chronological log of results. If you rank one entry in a collection, rank them all; a half-ranked collection reads as an accident.
 
+**6.5b — Developer-documentation articles.** A registered collection may set `theme: docs` to give its **article web pages only** demolab's built-in developer-documentation treatment: technical sans/mono typography, cool slate surfaces, documentation tables, code panels, and API-reference accents. The collection listing, experiment pages in the same collection, per-entry PDFs, and combined book retain the standard lab design. `docs` is currently the only built-in theme:
+
+```yaml
+collection-order: [python-sdk]
+collections:
+  python-sdk:
+    label: Python SDK
+    description: Guides and API reference for the Python package.
+    theme: docs
+```
+
+The theme styles ordinary Typst headings, prose, code, and tables automatically. A documentation article may add HTML-only `docs-toc`, `docs-note`, and `api-signature` elements for the richer components demonstrated by the shipped `ar028` example; keep a meaningful plain Typst structure around them so the article remains useful in PDF form.
+
 **6.6 — Citations & references.** Cite prior work with two `lib.typ` helpers, so numbering, linking, and the web popover all come for free — never hand-type a bracket or a manual list (HOUSESTYLE H24). Import both: `#import "/.demolab/lib.typ": cite, reference-list`.
 
 - **Inline** — `#cite(1, 2)` renders `[1, 2]`. The numbers are **author-managed** (you pass them), so there's no `.bib` file to keep in sync. On the web each number links to its entry.
@@ -118,6 +131,14 @@ Numbers must come from the run (§5.4) — never hand-type a literal that could
 
 See `ar006` for a worked example — ten references with DOIs, inline cites throughout, and the reference list at the foot of the body.
 
+**6.7 — Collaborative annotations are opt-in and web-only.** Set `annotations: hypothesis`
+in root `demolab.yaml` to embed the hosted Hypothesis client on every article and experiment,
+or put `annotations: "hypothesis"` in one writing's `meta` block to enable only that entry. An
+entry-level `annotations: none` disables a lab-wide setting. The client is never emitted into PDFs.
+Hypothesis owns annotation accounts, storage, private-group membership, anchoring, and threads;
+collaborators must choose their private group before posting if the discussion is not public. See
+demo article `ar027` for the complete setup and a live example.
+
 ## 7. Adding an experiment
 
 **7.1 — Tool subcommand.** Add a subcommand (or reuse one) in the relevant `tools/<tool>/tool.py`. Pass a `manifest` to `write_output` declaring the headline metrics (and a video, for a rendering tool).

{demolab_cli-2.2.1 → demolab_cli-2.4.0}/demolab_cli/runbooks/GETTING-STARTED.md

@@ -182,8 +182,10 @@ freestyling, not following this runbook.
    tagline, book/PDF title (defaults from the name), and **author + contact** (offer to pull
    from git config — they render as a byline under the homepage title and an
    `<meta name="author">`; contact, if given, links the byline). The engine defaults any key
-   you omit and updates never touch it; `demolab dev` hot-reloads, so they watch it change. Deeper
-   theming (`style.css`, `favicon.svg`) lives inside the engine package — leave it as advanced.
+   you omit and updates never touch it; `demolab dev` hot-reloads, so they watch it change. If an
+   article collection is developer documentation, offer its built-in `theme: docs` treatment
+   (RULES §6.5b); it affects only that collection's article web pages. Deeper theming
+   (`style.css`, `favicon.svg`) lives inside the engine package — leave it as advanced.
 
 5. **Publish to GitHub Pages?** *"Free, unless the repo is private."* Default yes; if no, skip —
    it all works locally. If yes: create + push a GitHub repo (`gh`), run `demolab deploy-setup`

{demolab_cli-2.2.1 → demolab_cli-2.4.0}/demolab_cli/scaffold/demo/demolab.yaml

@@ -7,8 +7,12 @@ book-title: Demolab — the book
 contents-title: Demolab — contents
 description: A lab notebook for computational science — reproducible results, published and citable.
 
-collection-order: [documentation]
+collection-order: [documentation, theme-demo]
 collections:
   documentation:
     label: Documentation
     description: "How demolab works, in reading order: what it is and why, setting up, the contract, the mechanics of experiments and writeups, and running the lab day to day."
+  theme-demo:
+    label: Developer docs theme
+    description: "A single-page showroom for the optional developer-documentation collection theme."
+    theme: docs

{demolab_cli-2.2.1 → demolab_cli-2.4.0}/demolab_cli/scaffold/demo/writings/ar025.typ

@@ -51,7 +51,10 @@
   work: an unregistered slug is simply title-cased for display (`neuron-models` becomes
   "Neuron Models"). The `collections:` map in `demolab.yaml` upgrades that: per slug, a
   `label` (the display name) and a `description` (shown under the label on the homepage
-  and at the top of the collection's own page).
+  and at the top of the collection's own page). A collection can also set `theme: docs`
+  to give only its article web pages a light developer-documentation treatment. Collection
+  listings, experiment pages, standalone PDFs, and the combined book keep the standard lab
+  design. `docs` is currently the only built-in theme.
 
   `collection-order:` is a list of slugs setting the homepage order. Collections you leave
   out of the list still appear; they trail after the listed ones. Two special cases:
@@ -90,11 +93,15 @@
   contents-title: Demolab — contents
   description: A lab notebook for computational science — reproducible results, published and citable.
 
-  collection-order: [documentation, slides]
+  collection-order: [documentation, theme-demo, slides]
   collections:
     documentation:
       label: Documentation
       description: "How demolab works, in reading order: what it is and why, setting up, the contract, the mechanics of experiments and writeups, and running the lab day to day."
+    theme-demo:
+      label: Developer docs theme
+      description: "A single-page showroom for the optional developer-documentation collection theme."
+      theme: docs
     slides:
       label: Talks & slides
       description: Deck PDFs from talks — paged-only, linked as PDF.

demolab_cli-2.4.0/demolab_cli/scaffold/demo/writings/ar027.typ

@@ -0,0 +1,77 @@
+#let meta = (
+  title: "Discussing a writeup inline",
+  date: "2026-08-07",
+  description: "Optional Hypothesis annotations let collaborators highlight a passage in a web article or experiment and discuss it in a private, threaded margin conversation.",
+  collection: "documentation",
+  status: "final",
+  order: 17,
+  annotations: "hypothesis",
+)
+
+#let hypothesis = "https://web.hypothes.is"
+
+#let body = [
+  A published result often needs a conversation before it needs another revision. Hypothesis adds
+  that conversation directly to a demolab web page: select a passage, attach a comment, and reply
+  in a shared thread. The annotation stays outside the scientific record, while the experiment,
+  figures, and PDF remain reproducible and unchanged.
+
+  This page is itself an example. Its `meta` block contains `annotations: "hypothesis"`, so the
+  Hypothesis control appears at the right edge of the web edition. Select this sentence and attach
+  a private note to test the complete path.
+
+  == Set up a private reading group
+
+  + Create free Hypothesis accounts for each collaborator.
+  + #link(hypothesis + "/help/how-to-create-a-private-group/")[Create a private group], then send
+    its invitation link to the people who should read and reply.
+  + Open an annotated demolab page, sign in through the sidebar, and select that private group
+    before posting. The public layer is a different destination; check the group name on every
+    new top-level comment when the discussion must remain private.
+
+  Replies form a thread beneath the selected passage. Hypothesis also supports page notes for
+  comments about the whole experiment and LaTeX between double dollar signs for mathematical
+  discussion.
+
+  == Enable annotations
+
+  To annotate every article and experiment, add one field to the root `demolab.yaml`:
+
+  ```yaml
+  annotations: hypothesis
+  ```
+
+  To enable only selected entries, omit the root field and add the provider to a writing's
+  metadata instead:
+
+  ```typ
+  #let meta = (
+    title: "A result to review",
+    date: "2026-08-07",
+    annotations: "hypothesis",
+  )
+  ```
+
+  Entry metadata wins over the lab setting. Set `annotations: none` on one entry to keep it
+  unannotated when the rest of the lab has Hypothesis enabled.
+
+  == What gets published
+
+  The setting adds the hosted Hypothesis client to web entry pages only. It does not add scripts
+  to the homepage, collection listings, standalone PDFs, or the combined book. Comments and group
+  membership live in Hypothesis rather than the git repository, so rebuilding the site does not
+  publish a private discussion or alter a recorded result.
+
+  An annotation targets the page URL and records several descriptions of the selected text. Small
+  layout changes and unrelated edits usually leave it attached. Moving the page to another URL,
+  deleting the selected passage, or substantially rewriting its context can orphan it. Keep entry
+  IDs stable and resolve important review comments before replacing the prose they target.
+
+  == Operational boundary
+
+  This option loads JavaScript from `hypothes.is` and sends annotation content to the Hypothesis
+  service. That is an intentional external dependency, not part of demolab's committed research
+  record. Do not enable it for material whose hosting or data policy forbids that service. Review
+  #link(hypothesis + "/privacy/")[Hypothesis privacy information] with your collaborators before
+  using it for sensitive or unpublished work.
+]

demolab_cli-2.4.0/demolab_cli/scaffold/demo/writings/ar028.typ

@@ -0,0 +1,148 @@
+#let meta = (
+  title: "LatticeCache Python SDK",
+  date: "2026-08-14",
+  description: "Fake developer documentation and API reference for a fictional Python caching library.",
+  collection: "theme-demo",
+  status: "final",
+)
+
+#let body = [
+  LatticeCache is a fictional Python library for caching deterministic function calls on disk.
+  It is intentionally small, typed, and boring: the same inputs produce the same cache key, and
+  expired values disappear without ceremony.
+
+  #context if target() == "html" {
+    html.elem("nav", attrs: (class: "docs-toc", "aria-label": "On this page"), {
+      html.elem("p", attrs: (class: "docs-toc-title"), [On this page])
+      html.elem("ul", {
+        html.elem("li", html.elem("a", attrs: (href: "#installation"), [Installation]))
+        html.elem("li", html.elem("a", attrs: (href: "#quick-start"), [Quick start]))
+        html.elem("li", html.elem("a", attrs: (href: "#configuration"), [Configuration]))
+        html.elem("li", html.elem("a", attrs: (href: "#api-reference"), [API reference]))
+        html.elem("li", html.elem("a", attrs: (href: "#cache"), [`Cache`]))
+        html.elem("li", html.elem("a", attrs: (href: "#cached"), [`cached`]))
+      })
+    })
+  }
+
+  == Installation
+
+  LatticeCache requires Python 3.11 or later. Install it from the imaginary package index:
+
+  ```sh
+  pip install latticecache
+  ```
+
+  #context if target() == "html" {
+    html.elem("aside", attrs: (class: "docs-note"), [
+      *Demo package.* `latticecache` does not exist. This page is sample content for demolab's
+      optional article treatment, not advice to paste mysterious packages into your terminal.
+    ])
+  }
+
+  == Quick start
+
+  Create one cache and call `get_or_set` with a stable key. The factory runs only when no live
+  value exists.
+
+  ```python
+  from datetime import timedelta
+  from latticecache import Cache
+
+  cache = Cache(".cache/weather")
+
+  forecast = cache.get_or_set(
+      "madrid:2026-08-14",
+      factory=lambda: fetch_forecast("Madrid"),
+      ttl=timedelta(minutes=15),
+  )
+  ```
+
+  Values are encoded as JSON by default. Supply a codec when storing dataclasses, NumPy arrays,
+  or other objects that JSON cannot represent.
+
+  == Configuration
+
+  #table(
+    columns: (1.1fr, 1fr, 2.3fr),
+    [*Option*], [*Default*], [*Meaning*],
+    [`namespace`], [`"default"`], [Prefix used to isolate cache keys],
+    [`max_bytes`], [`256 MiB`], [Soft size limit checked after each write],
+    [`serializer`], [`"json"`], [Built-in `json`, `text`, or a custom codec],
+    [`read_only`], [`False`], [Allow reads but never create or refresh entries],
+  )
+
+  Configuration may be passed to `Cache` directly or loaded from `pyproject.toml` under
+  `[tool.latticecache]`. Constructor arguments win when both are present.
+
+  == API reference
+
+  === `Cache`
+
+  #context if target() == "html" {
+    html.elem("div", attrs: (class: "api-signature"), [
+      `class latticecache.Cache(path, *, namespace="default", max_bytes=268435456, read_only=False)`
+    ])
+  }
+
+  A filesystem-backed cache. Creating an instance makes its directory lazily on the first write;
+  constructing a read-only cache never changes the filesystem.
+
+  ==== Parameters
+
+  #table(
+    columns: (1fr, 1fr, 2.4fr),
+    [*Name*], [*Type*], [*Description*],
+    [`path`], [`str | Path`], [Directory containing cached values and metadata],
+    [`namespace`], [`str`], [Logical partition included in every derived key],
+    [`max_bytes`], [`int`], [Approximate limit before least-recently-used eviction],
+    [`read_only`], [`bool`], [Disable writes, refreshes, and eviction],
+  )
+
+  ==== `Cache.get_or_set`
+
+  #context if target() == "html" {
+    html.elem("div", attrs: (class: "api-signature"), [
+      `get_or_set(key, factory, *, ttl=None) -> Any`
+    ])
+  }
+
+  Return the live value stored under `key`. If the key is absent or expired, call `factory`,
+  store its result atomically, and return the new value.
+
+  - *Raises `ReadOnlyMiss`* when a read-only cache has no live value.
+  - *Raises `EncodeError`* when the configured serializer rejects the factory result.
+  - The factory's own exceptions pass through unchanged and are never cached.
+
+  ==== `Cache.invalidate`
+
+  #context if target() == "html" {
+    html.elem("div", attrs: (class: "api-signature"), [`invalidate(key) -> bool`])
+  }
+
+  Remove one key. Returns `true` when an entry existed and `false` when there was nothing to do.
+
+  === `cached`
+
+  #context if target() == "html" {
+    html.elem("div", attrs: (class: "api-signature"), [
+      `latticecache.cached(cache, *, ttl=None, key=None) -> Callable`
+    ])
+  }
+
+  Decorate a deterministic function. By default, the key combines the function's qualified name,
+  its source fingerprint, and a canonical encoding of positional and keyword arguments.
+
+  ```python
+  from latticecache import Cache, cached
+
+  cache = Cache(".cache/models", namespace="v2")
+
+  @cached(cache, ttl=3600)
+  def load_model(model_id: str, *, quantized: bool = False):
+      return download_model(model_id, quantized=quantized)
+  ```
+
+  Mutable global state is not part of the derived key. Pass every input explicitly or provide a
+  custom `key` function; invisible dependencies and caches are natural enemies.
+]

{demolab_cli-2.2.1 → demolab_cli-2.4.0}/demolab_cli/scaffold/skeleton/demolab.yaml

@@ -14,6 +14,11 @@ description: A lab notebook for computational science — reproducible results,
 # author: Your Name
 # contact: you@example.com
 
+# Optional collaborative inline comments on web articles and experiments. Readers select text
+# and discuss it through Hypothesis accounts and groups; PDFs are unchanged. Set this lab-wide,
+# or omit it here and add `annotations: "hypothesis"` to selected writings' `meta` blocks.
+# annotations: hypothesis
+
 # Optional custom landing page — not a config key: create a `landing.typ` at the repo root
 # exporting `#let body = [...]` and the homepage renders it (web only) instead of the collection
 # directory, below the title/tagline/byline above. Delete the file to get the directory back.
@@ -21,12 +26,15 @@ description: A lab notebook for computational science — reproducible results,
 
 # Homepage collections. Entries are grouped by their `collection:` meta field; this
 # registry gives each collection a display label + description and sets the order. A
-# collection with no entry here still works — its slug is just title-cased.
+# collection with no entry here still works — its slug is just title-cased. Add
+# `theme: docs` to a collection whose articles should have a light developer-documentation
+# web treatment. Collection listings, experiments, and PDFs retain the standard design.
 collection-order: [documentation, neuron-models, mujoco, streamlit, slides]
 collections:
   documentation:
     label: Documentation
     description: "How demolab works: getting started, the always-on guides that set the conventions, and the on-demand runbooks the agent runs."
+    # theme: docs
   neuron-models:
     label: Neuron models
     description: Integrate-and-fire neurons and the membrane biophysics behind them.

{demolab_cli-2.2.1 → demolab_cli-2.4.0}/demolab_cli/test_engine_build.py

@@ -83,6 +83,11 @@ def test_demo_fixture_builds_full_site(tmp_path: Path) -> None:
     root = tmp_path / "repo"
     root.mkdir()
     _assemble(root, demo=True)
+    # The docs treatment is article-only even when an experiment shares the collection.
+    (root / "writings" / "exp099.typ").write_text(
+        '#let meta = (title: "Theme boundary", date: "2026-08-14", collection: "theme-demo")\n'
+        '#let body = [An experiment keeps the standard presentation.]\n'
+    )
     _build(root)
 
     site = root / "artifacts" / "site"
@@ -102,6 +107,43 @@ def test_demo_fixture_builds_full_site(tmp_path: Path) -> None:
     assert '<ul class="coll-list"' in index, "collection directory visible in a user lab"
     entry = (site / "ar018.html").read_text()
     assert "<img" in entry or "<svg" in entry, "a figure made it into the entry page"
+    assert 'class="theme-docs"' not in entry, "ordinary collections retain the journal theme"
+    collection = (site / "documentation.html").read_text()
+    assert 'class="listing theme-docs"' not in collection, "ordinary collection listing stays neutral"
+    themed_entry = (site / "ar028.html").read_text()
+    assert 'class="theme-docs"' in themed_entry, "collection theme follows articles onto the web"
+    assert 'class="docs-toc"' in themed_entry, "developer-docs demo includes an on-page TOC"
+    assert 'href="#api-reference"' in themed_entry, "TOC links to generated heading anchors"
+    assert "class latticecache.Cache" in themed_entry, "demo includes a representative API reference"
+    themed_experiment = (site / "exp099.html").read_text()
+    assert 'class="theme-docs"' not in themed_experiment, "experiments stay on the standard theme"
+    themed_collection = (site / "theme-demo.html").read_text()
+    assert 'class="listing theme-docs"' not in themed_collection, "collection listings stay neutral"
+    assert 'class="theme-docs"' not in index, "collection theme does not leak onto the homepage"
+    annotated = (site / "ar027.html").read_text()
+    assert 'src="https://hypothes.is/embed.js"' in annotated, "opted-in entry embeds Hypothesis"
+    assert 'src="https://hypothes.is/embed.js"' not in entry, "annotations remain opt-in"
+
+
+def test_lab_wide_hypothesis_annotations_only_touch_entries(tmp_path: Path) -> None:
+    root = tmp_path / "repo"
+    root.mkdir()
+    _assemble(root, demo=True)
+    with (root / "demolab.yaml").open("a", encoding="utf-8") as config:
+        config.write("\nannotations: hypothesis\n")
+    opted_out = root / "writings" / "ar018.typ"
+    opted_out.write_text(
+        opted_out.read_text(encoding="utf-8").replace("order: 1,", "order: 1,\n  annotations: none,"),
+        encoding="utf-8",
+    )
+    _build(root)
+
+    site = root / "artifacts" / "site"
+    embed = 'src="https://hypothes.is/embed.js"'
+    assert embed in (site / "ar019.html").read_text(), "root config enables normal entries"
+    assert embed not in (site / "ar018.html").read_text(), "entry metadata can opt out"
+    assert embed not in (site / "index.html").read_text(), "homepage remains annotation-free"
+    assert embed not in (site / "documentation.html").read_text(), "listings remain annotation-free"
 
 
 def test_curated_collection_lists_in_reading_order(tmp_path: Path) -> None:

{demolab_cli-2.2.1 → demolab_cli-2.4.0}/demolab_cli/typ/entry.typ

@@ -5,7 +5,8 @@
 #let has-brand = sys.inputs.at("has-brand", default: "false") == "true"
 #let config = if has-brand { yaml("/demolab.yaml") } else { (:) }
 #let brand = default-brand + config
+#let annotations = config.at("annotations", default: none)
 #import "/writings/" + entry-id + ".typ" as writing
 
 #set document(title: writing.meta.title)
-#numbered-pages(entry-page(writing.meta, writing.body, id: entry-id, brand: brand))
+#numbered-pages(entry-page(writing.meta, writing.body, id: entry-id, brand: brand, annotations: annotations))

{demolab_cli-2.2.1 → demolab_cli-2.4.0}/demolab_cli/typ/lib.typ

@@ -31,7 +31,7 @@
 }
 
 // --- web-styles: inject the stylesheet + head meta into HTML pages (ignored in the PDF pass) ---
-#let web-styles(brand: default-brand) = context {
+#let web-styles(brand: default-brand, annotations: none) = context {
   if target() == "html" {
     html.elem("link", attrs: (rel: "icon", type: "image/svg+xml", href: "favicon.svg"))
     html.elem("style", read("/.demolab/style.css"))
@@ -42,6 +42,11 @@
     }
     // hover popovers for inline citations (no-op on pages without cites)
     html.elem("script", attrs: (src: "cite-popover.js", defer: ""))[]
+    // Optional collaborative web annotations. The hosted Hypothesis client owns accounts,
+    // private groups, storage, anchoring, and threads; demolab only opts this page into it.
+    if annotations == "hypothesis" {
+      html.elem("script", attrs: (src: "https://hypothes.is/embed.js", async: ""))[]
+    }
   }
 }
 
@@ -185,6 +190,11 @@
 #let title-case(slug) = slug.split("-").map(w => if w.len() > 0 { upper(w.slice(0, 1)) + w.slice(1) } else { w }).join(" ")
 #let collection-label(slug, meta) = meta.at(slug, default: (:)).at("label", default: title-case(slug))
 #let collection-description(slug, meta) = meta.at(slug, default: (:)).at("description", default: none)
+#let collection-theme(slug, meta) = meta.at(slug, default: (:)).at("theme", default: none)
+#let theme-class(theme, base: none) = {
+  let classes = if base == none { () } else { (base,) }
+  (classes + if theme == none { () } else { ("theme-" + str(theme),) }).join(" ")
+}
 #let collection-rank(slug, order) = {
   let i = order.position(s => s == slug)
   if i == none { order.len() } else { i }
@@ -393,8 +403,19 @@
   html.elem("p", attrs: (class: "page-foot"), html.elem("a", attrs: (href: "index.html"), [← back to all entries]))
 }
 
-#let entry-page(meta, body, id: none, brand: default-brand) = {
-  web-styles(brand: brand)
+#let entry-page(meta, body, id: none, kind: "article", brand: default-brand, annotations: none, collection-meta: (:)) = {
+  // Entry metadata can override the lab-wide provider. `none` disables a global provider for
+  // one entry; absent metadata inherits the root demolab.yaml setting.
+  let annotation-provider = meta.at("annotations", default: annotations)
+  web-styles(brand: brand, annotations: annotation-provider)
+  // Collection themes are a light, web-only treatment for articles. Experiments, collection
+  // listings, PDFs, and the combined book deliberately retain the standard lab presentation.
+  let theme = collection-theme(meta.at("collection", default: "uncategorized"), collection-meta)
+  context {
+    if target() == "html" and kind == "article" and theme != none {
+      html.elem("div", attrs: (class: theme-class(theme), "aria-hidden": "true"))[]
+    }
+  }
   set text(font: "New Computer Modern", size: 11pt)
   // Restart figure numbering per entry: the whole bundle is one compile, so Typst's global
   // figure counter would otherwise carry across every document. Each entry (its page + its

{demolab_cli-2.2.1 → demolab_cli-2.4.0}/demolab_cli/typ/main.typ

@@ -24,6 +24,7 @@
 // read from it too. Absent ⇒ engine defaults + derivation-only collections.
 #let config = if manifest.has_brand_config { yaml("/demolab.yaml") } else { (:) }
 #let brand = default-brand + config
+#let annotations = config.at("annotations", default: none)
 #let collection-order = config.at("collection-order", default: ())
 #let collection-meta = config.at("collections", default: (:))
 
@@ -79,8 +80,8 @@
   }
 }
 #for e in entries {
-  [#document(e.id + ".html", title: [#e.meta.title])[#entry-page(e.meta, e.body, id: e.id, brand: brand)]]
-  [#document("pdfs/" + e.id + ".pdf", title: [#e.meta.title])[#numbered-pages(entry-page(e.meta, e.body, id: e.id, brand: brand))]]
+  [#document(e.id + ".html", title: [#e.meta.title])[#entry-page(e.meta, e.body, id: e.id, kind: e.kind, brand: brand, annotations: annotations, collection-meta: collection-meta)]]
+  [#document("pdfs/" + e.id + ".pdf", title: [#e.meta.title])[#numbered-pages(entry-page(e.meta, e.body, id: e.id, kind: e.kind, brand: brand, annotations: annotations, collection-meta: collection-meta))]]
 }
 // stub pages for entries that failed to build — a visible "this page failed" placeholder at the
 // entry's own URL (web only; excluded from listings + the book), so the rest of the site is fine.

{demolab_cli-2.2.1 → demolab_cli-2.4.0}/demolab_cli/typ/style.css

@@ -356,6 +356,105 @@ pre {
 }
 pre code { font-size: 1em; }
 
+/* Built-in article treatment: developer documentation. A collection opts its articles in
+   with `theme: docs` in demolab.yaml. This stays close to demolab's default spacing and
+   structure while using the neutral sans/mono pairing, cool slate surfaces, and blue accent
+   readers expect from contemporary technical references.
+   Collection listings, experiments, PDFs, and the combined book remain unchanged. */
+body:has(.theme-docs) {
+  max-width: 46em;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Inter, Helvetica, Arial, sans-serif;
+  font-size: 17px;
+  line-height: 1.65;
+  color: #172033;
+  --ink: #172033;
+  --muted: #64748b;
+  --rule: #e2e8f0;
+  --rule-strong: #cbd5e1;
+  --paper-tint: #f8fafc;
+  --selection: #dbeafe;
+  --docs-accent: #315faa;
+  --mono: ui-monospace, "SFMono-Regular", Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+}
+body:has(.theme-docs) h1,
+body:has(.theme-docs) h2,
+body:has(.theme-docs) h3,
+body:has(.theme-docs) h4,
+body:has(.theme-docs) h5,
+body:has(.theme-docs) h6 {
+  color: #111827;
+  font-family: inherit;
+  letter-spacing: -.018em;
+}
+body:has(.theme-docs) h5 {
+  margin: 1.6rem 0 .4rem;
+  font-size: .95rem;
+  line-height: 1.35;
+}
+body:has(.theme-docs) h6 {
+  margin: 1.35rem 0 .35rem;
+  font-size: .9rem;
+  line-height: 1.35;
+}
+body:has(.theme-docs) a { color: var(--docs-accent); text-decoration-color: #9db4da; }
+body:has(.theme-docs) .home-link,
+body:has(.theme-docs) .entry-meta,
+body:has(.theme-docs) .page-foot { color: var(--muted); }
+body:has(.theme-docs) code {
+  padding: .08em .28em;
+  border-radius: 3px;
+  color: #334155;
+  background: #f1f5f9;
+  font-family: var(--mono);
+  font-size: .86em;
+}
+body:has(.theme-docs) pre {
+  border-color: #d0d7de;
+  border-radius: 6px;
+  color: #e2e8f0;
+  background: #172033;
+  box-shadow: 0 1px 2px rgba(15, 23, 42, .06);
+}
+body:has(.theme-docs) pre code { padding: 0; color: inherit; background: transparent; font-size: 1em; }
+body:has(.theme-docs) table { width: 100%; font-size: .88rem; }
+body:has(.theme-docs) th,
+body:has(.theme-docs) td { border-color: var(--rule); padding: .55rem .7rem; vertical-align: top; }
+body:has(.theme-docs) th { color: #334155; background: #f1f5f9; }
+body:has(.theme-docs) td { color: #334155; }
+body:has(.theme-docs) td:last-child,
+body:has(.theme-docs) th:last-child { text-align: left; font-variant-numeric: normal; }
+.docs-toc {
+  margin: 1.5rem 0 2rem;
+  padding: .85rem 1rem;
+  border: 1px solid var(--rule);
+  border-radius: 6px;
+  background: var(--paper-tint);
+}
+.docs-toc-title { margin: 0 0 .35rem; color: #334155; font-size: .88rem; font-weight: 650; }
+.docs-toc ul { columns: 2; margin: 0; padding-left: 1.15rem; }
+.docs-toc li { margin: .15rem 0; color: var(--muted); font-size: .9rem; }
+.docs-note {
+  margin: 1.25rem 0;
+  padding: .75rem 1rem;
+  border-left: 3px solid var(--docs-accent);
+  color: #334155;
+  background: #eff6ff;
+}
+.api-signature {
+  margin: .8rem 0 1rem;
+  padding: .75rem .9rem;
+  overflow-x: auto;
+  border: 1px solid #dbe3ee;
+  border-left: 3px solid #93add3;
+  border-radius: 4px;
+  color: #1e3a5f;
+  background: #f8fafc;
+  font-family: var(--mono);
+  font-size: .82rem;
+  line-height: 1.5;
+}
+.api-signature code { padding: 0; color: inherit; background: transparent; font-size: 1em; }
+
 @media (max-width: 42rem) {
   body { margin-top: 2rem; margin-bottom: 2.5rem; }
   .welcome { margin-bottom: 2rem; }
@@ -364,6 +463,7 @@ pre code { font-size: 1em; }
   .welcome-runbook { display: block; padding: .6rem 0; }
   .welcome-runbook dt { margin-bottom: .2rem; }
   .entry-row { align-items: flex-start; gap: .5rem; }
+  .docs-toc ul { columns: 1; }
 }
 
 @media (max-width: 22rem) {

demolab_cli-2.2.1/demolab_cli/VERSION

@@ -1 +0,0 @@
-2.2.1